home *** CD-ROM | disk | FTP | other *** search
/ The Complete Windows Set / The Complete Windows Set.iso / SOFTERM / SCRIPTS.DOC < prev    next >
Text File  |  1992-08-18  |  152KB  |  4,022 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                       Script Files
  8.  
  9.                       Important
  10.                       To be used, a script file must be configured in a
  11.                       Script profile.
  12.  
  13.                       Softerm's script files act much like the operating
  14.                       system's batch and command files by automating
  15.                       repetitious operations.  The script language is
  16.                       optimized for communications tasks.  Because
  17.                       communications operations involve data, Softerm's
  18.                       Script language includes many file and data
  19.                       manipulation functions.
  20.  
  21.                       Script files are standard text files and can be
  22.                       created using almost any editor or word processing
  23.                       program which can create and save files in standard
  24.                       ASCII format.  A description of the command syntax is
  25.                       included in this section.
  26.  
  27.                       Script Language Capabilities
  28.  
  29.                       The Script language format is constructed from the
  30.                       basic capabilities typically asssociated with
  31.                       programming languages.  These capabilities include:
  32.  
  33.                       Functions
  34.                       o   File transfer, disk file manipulation, error
  35.                           processing, operator input
  36.  
  37.                       Text String Manipulation
  38.                       o   Maximum text string length of 255 characters
  39.                       o   Text string catenation
  40.  
  41.                       Numeric Operations
  42.                       o   Numeric range of -2,147,483,648 to +2,147,483,647
  43.                       o   Operations including Not, Addition, Subtracttion,
  44.                           Multiplication, Division, Arithmetic AND,
  45.                           Arithmetic OR, Arithmetic XOR, Assignment
  46.  
  47.                       Variable Manipulation
  48.                       o   Assignment
  49.  
  50.                       Conditional Processing
  51.                       o   IF/ELSE, Less Than, Less Than or Equal To, Equal
  52.                           To, Not Equal To, Greater Than or Equal To,
  53.                           Greater Than, Logical AND, Logical OR
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.                       Script File Operation
  61.  
  62.                       When a script file is started, a window opens and,
  63.                       depending upon the setting of script window control
  64.                       functions, displays some or all of this information:
  65.  
  66.                       o A title that contains the Session name and file
  67.                         name of the running script.
  68.                       o A menu that provides control over the script file
  69.                         operation:
  70.                         o Cancel script operation
  71.                         o Start and Cancel the Watch script function
  72.                           operation
  73.                       o A client area where script commands are displayed
  74.                         during Watch and where the MESSAGE command
  75.                         displays text.
  76.                       o The current path being used by the Script.
  77.                       o The full path and file name of the active script.
  78.  
  79.                       Operation Message File
  80.                       When operation of a script file starts and ends,
  81.                       appropriate information text messages are written to
  82.                       the file, SOFTERM.MSG, in the user's SOFTERM write
  83.                       file directory.  This information typically will
  84.                       contain the following:
  85.  
  86.                       o Session name
  87.                       o Script file name
  88.                       o Initiation message
  89.                       o Operation error message (if applicable)
  90.                       o Statement where operation error occurred
  91.                       o Stop message:  normally or by operator
  92.  
  93.                       In Case of Error
  94.                       When a function produces an error other than a
  95.                       simple file or data processing error, one of the
  96.                       following will occur:
  97.  
  98.                       1. Fatal errors will cause script file operation to
  99.                          be cancelled.
  100.                       2. Non-fatal errors will cause script file operation
  101.                          to continue at the defined error processing label
  102.                          (determined by the ONERR function) or, if no
  103.                          error processing label is defined, script file
  104.                          operation will be cancelled.  Read-only system
  105.                          variables are available that will contain the
  106.                          error code, error level and error text for the
  107.                          implementation of suitable error recovery
  108.                          procedures.
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.                                               - 2 -
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.                       Script Language Syntax
  125.  
  126.                       This section provides a brief overview of the
  127.                       Softerm script language.  Each component also is
  128.                       described fully in separate sections.
  129.  
  130.                       Syntax Rules
  131.  
  132.                       1. An input line consists entirely of the data
  133.                          between one '>' character which is in the first
  134.                          column and the next '>' character which is in the
  135.                          first column.  The exception is, of course, the
  136.                          last command in the script file.
  137.  
  138.                       2. An input line may contain only a single script
  139.                          language statement.  However, a statement may
  140.                          consist of multiple functions.
  141.  
  142.                       3. Text strings and variables containing text
  143.                          strings are interchangeable throughout the script
  144.                          language.
  145.  
  146.                       4. Numerics and variables containing numerics are
  147.                          interchangeable throughout the script language.
  148.  
  149.                       Variable Classification
  150.                       Softerm's script language recognizes three
  151.                       classifications of variables:
  152.  
  153.                       o User-defined variables, such as:
  154.                             > TXTVAR = 'This is a test.'
  155.                             > NUMVAR = 42
  156.  
  157.                       o Assignable predefined system variables, such as:
  158.                             > BAUD = 9600
  159.  
  160.                       o Read-only predefined system variables, such as:
  161.                             > IF ERRORLEVEL == 6
  162.  
  163.                       Function Identification
  164.                       Functions are identified as such by enclosing their
  165.                       arguments between parentheses.  This includes those
  166.                       functions that require no arguments.  For example:
  167.  
  168.                             > EXAMPLE()       ;is a function
  169.                             > EXAMPLE         ;is a variable
  170.  
  171.                       Result Codes
  172.                       All functions return a result so that relatively
  173.                       complex and meaningful statements may be
  174.                       constructed.  For example, while the following
  175.                       command is valid, little can be done with it:
  176.  
  177.                             > NEXTFILE (filedef)
  178.  
  179.  
  180.  
  181.                                               - 3 -
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.                       However, by using the returned result, a useful
  189.                       statement is created, such as:
  190.  
  191.                             > SFILE = NEXTFILE (filedef)
  192.                             > IF GETLENGTH (SFILE) < 5
  193.                             > GOTO NO_MORE
  194.                             > ENDIF
  195.                       Important:  Except where noted, this result code
  196.                       will be a zero value for success or an error code
  197.                       value in the case of a failure.
  198.  
  199.                       Arguments
  200.                       A function argument may be any valid expression.
  201.                       For example:
  202.  
  203.                       > WRITELINE(HANDLE,'Error code = ' + VALTOSTR(ERRORCODE))
  204.  
  205.                       Function arguments must be separated with commas.
  206.                       Function arguments that have predefined default
  207.                       values may be specified as null.  For example:
  208.  
  209.                             > EXAMPLE(arg1,,,arg4)
  210.  
  211.                       Trailing function arguments that have predefined
  212.                       default values may be omitted.
  213.  
  214.                       Remarks
  215.                       A remark is all remaining data within a statement
  216.                       that follows a semi-colon.
  217.  
  218.                             > EXAMPLE(arg1,arg2)    ;this is a remark
  219.  
  220.                       Labels
  221.                       A label that is the target of a discontinuity is
  222.                       signified by a colon following the label operand,
  223.                       such as:
  224.  
  225.                             > ERRORLABEL:
  226.                             > BEGIN:
  227.  
  228.                       Label names are not case sensitive, but they must
  229.                       begin with a letter.  Only the first 10 characters
  230.                       are significant.
  231.  
  232.                       User Variable
  233.                       User variables are not case sensitive, but they must
  234.                       begin with a letter.
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.                                               - 4 -
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.                       Script File Format
  253.                       Script files exist on disk as text files.  Within
  254.                       the text file, a function is defined by a keyword
  255.                       and possible arguments. The general format of a
  256.                       command in a script file is:
  257.  
  258.                             > RESULT = KEYWORD (arg1,arg2,...,argn)
  259.  
  260.                       The > character is required to identify the line as
  261.                       the start of a statement and must be the first non-
  262.                       blank, non-tab character on the line.  Any other
  263.                       character occurring as the first non-blank, non-tab
  264.                       character on the line indicates that the line is a
  265.                       continuation of a previous command.  Carriage
  266.                       returns and line feeds and any blank or tab
  267.                       characters following the carriage return or line
  268.                       feed are considered to be white space and may be
  269.                       used to separate keywords, arguments, and switches.
  270.  
  271.                       Inserting Special Functions
  272.                       The acronyms listed in Appendix A, ASCII Character
  273.                       Codes, and the tilde (~) character are used to
  274.                       insert characters which normally are interpreted as
  275.                       special functions into an argument.  Command lines
  276.                       can contain any of the 128 ASCII characters,
  277.                       including control characters.  For example, the
  278.                       following character sequences can be used to allow
  279.                       function characters to be inserted in strings:
  280.  
  281.                       Sequence    Function
  282.                       [CR]        Insert a carriage return into strings
  283.                       [LF]        Insert a line feed into strings
  284.                       [ddd]       Insert a character into strings where
  285.                                   ddd is the decimal ASCII value of the
  286.                                   character from 0-255.  Up to 3 decimal
  287.                                   digits can be used.  For example, [7]
  288.                                   will insert a BEEP.
  289.                       ~any char   Insert characters into strings.  For
  290.                                   example, use ~~ to insert a tilde and ~[
  291.                                   to insert a bracket.  Note:  The tilde
  292.                                   prefix can be redefined by the ESCAPE
  293.                                   assignable predefined system variable
  294.                                   for use within Script functions.
  295.  
  296.                       Note:  The conversion from internal nomenclature to
  297.                       destination character is performed only when the
  298.                       text is prepared for transmission, such as by the
  299.                       Send, Receive and Xmit_Wait functions.
  300.  
  301.                       Directory Paths and File Names
  302.                       File names used with these commands may include a
  303.                       drive specifier and a complete directory path from
  304.                       the root directory of the drive, including the
  305.                       special symbols backslash (\), period (.), or double
  306.  
  307.  
  308.  
  309.                                               - 5 -
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.                       period (..).  If no directory path is specified, the
  317.                       directory path displayed on the bottom row of the
  318.                       progress frame window will be used.  If the direc-
  319.                       tory path specified does not begin with the root
  320.                       directory, Softerm assumes the directory path
  321.                       specified begins with the current default directory.
  322.  
  323.                       Wildcard Characters
  324.                       Softerm allows global or wildcard characters to be
  325.                       used in file names for most file transfer commands
  326.                       performed by Softerm.  The wildcard characters
  327.                       asterisk (*) and question mark (?) indicate the
  328.                       portion of a file name which may be ignored or which
  329.                       may match any series of characters.  The asterisk is
  330.                       used to match any string of characters and the
  331.                       question mark is used to match single characters.
  332.                       An * used alone or *.* will match all file names.
  333.                       An *. will match only file names with no extension.
  334.  
  335.                       The use of file name wildcard characters is
  336.                       identical to the operation of these characters when
  337.                       specified for standard DOS operations.  The command
  338.                       will be performed on all files whose file names meet
  339.                       the subset specification.
  340.  
  341.                       Script File Language
  342.  
  343.                       Softerm's script file script language consists of
  344.                       three basic groups:  Variables and Parameters;
  345.                       Functions;  and Directives.
  346.                       Variables and Parameters
  347.                       The Softerm script language can use string
  348.                       variables, consisting of sequences of alphanumeric
  349.                       text up to 255 characters long, and numeric
  350.                       variables, consisting of an integer from
  351.                       -2,147,483,648 through +2,147,483,647.
  352.  
  353.                       Characters in a string are numbered from left to
  354.                       right beginning with 1.  A number of functions are
  355.                       defined for the manipulation of the variables.
  356.  
  357.                       Important:  If you set a variable equal to a numeric
  358.                       value, remember that Softerm stores numeric values
  359.                       in binary format;  not decimal.  Refer to the
  360.                       description of the VALTOSTR() function which
  361.                       converts binary data to decimal.
  362.  
  363.                       Variables are referenced by a name which consists of
  364.                       an alphanumeric string between 1 and 255 characters
  365.                       in length and which begins with an alpha character.
  366.  
  367.                       Note:  The space used to store variable names and
  368.                       values is limited.  If many variables are used in a
  369.  
  370.  
  371.  
  372.  
  373.                                               - 6 -
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.                       script file, the length of variable names should be
  381.                       kept to a minimum.
  382.  
  383.                       Script Variables
  384.                       Script Variables, also called Parameters, are a
  385.                       special type of string variable.  These text
  386.                       variables are used to import values to, and export
  387.                       values from, script files.
  388.  
  389.                       Softerm recognizes five Script Variables, each of
  390.                       which can be 64 characters long.  Values for these
  391.                       parameters can be assigned within script files.  In
  392.                       addition, these parameters can be defined when a
  393.                       script file is initiated and used by the script file
  394.                       as arguments to modify the operation of the script
  395.                       file.  For additional information, please refer to
  396.                       the Script File Profile and Session Window: Options
  397.                       Menu chapters.
  398.  
  399.                       Script Variables are referenced by the special
  400.                       symbols SV1 through SV5, representing parameter 1
  401.                       through parameter 5, respectively.  When encountered
  402.                       in a script file, the value of the specified Script
  403.                       Variable is substituted in the script file for the
  404.                       parameter name before the command containing the
  405.                       parameter is evaluated.  This allows the
  406.                       modification of Script Variable values by the script
  407.                       file.
  408.  
  409.                       When a CHAIN command is performed to stop the
  410.                       current script file and start another one, the new
  411.                       script receives all the defined variables.  This
  412.                       allows the values of variables from one script file
  413.                       to be passed to another script file.  All variables,
  414.                       except the ERRORCODE variable and the Script
  415.                       Variables, may be cleared with the VCLEAR command.
  416.                       This allows unused variable storage to be reclaimed.
  417.  
  418.                       Expressions
  419.                       An expression is a series of one or more variables,
  420.                       constants or literals (operands) separated by
  421.                       operators.  The evaluation of an expression yields
  422.                       either a string or a numeric result, depending on
  423.                       the type of operators in the expression.
  424.  
  425.                       Constants are numeric values and may be combined
  426.                       with other constants or numeric variables in an
  427.                       expression.
  428.  
  429.                       Literals are string values and may be combined with
  430.                       other literals or string variables in an expression.
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.                                               - 7 -
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.                       The following command illustrates the definition of
  445.                       a numeric variable:
  446.  
  447.                             > NUMBER = 5
  448.  
  449.                       The result of this command is to define NUMBER as a
  450.                       numeric variable and assign it the constant value of
  451.                       5.  The following commands do the same thing:
  452.  
  453.                             > NUMBER = 2
  454.                             > NUMBER = 10 / NUMBER  ; / signifies
  455.                       division.
  456.  
  457.                       The following illustrates the definition of a string
  458.                       variable:
  459.  
  460.                             > STRING = "Hello, Mikey"
  461.  
  462.                       The result of this command is to define STRING as a
  463.                       string variable and assign it the literal value of
  464.                       "Hello, Mikey".  The following command does the
  465.                       same:
  466.  
  467.                             > STRING = 'Hello, ' + 'Mikey'
  468.  
  469.                       The plus sign is a catenation operator, used to
  470.                       combine the two strings.
  471.  
  472.                       Expression Evaluation Order
  473.                       Expressions are evaluated in left to right order
  474.                       (there is no operator precedence), unless
  475.                       parentheses are used to alter the evaluation order.
  476.                       Using parentheses will force the evaluation of the
  477.                       expression inside the parentheses before combining
  478.                       it with the operand to the left of the parenthesized
  479.                       expression.
  480.  
  481.                       Numeric Constants
  482.                       Numeric constants may be integer decimal, binary,
  483.                       octal, and hexadecimal numbers and may range in
  484.                       value from -2,147,483,648 through +2,147,483,647.
  485.                       The format of a numeric constant is:
  486.  
  487.                       Type         Format     Example
  488.                       Decimal      ±nnnn      15
  489.                       Octal        ±0nnnnO    017O
  490.                       Hexadecimal  ±0nnnnH    0FH
  491.                       Binary       ±0nnnnB    01111B
  492.  
  493.                       Important:  A numeric constant not beginning with 0
  494.                       is treated as a decimal.
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.                                               - 8 -
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.                       Literals
  509.                       Literals are strings enclosed in single (') or
  510.                       double quotes (").  They may contain any
  511.                       alphanumeric characters and may be up to 255
  512.                       characters in length.
  513.  
  514.                       Operators
  515.                       !  Logical Not        +  Plus
  516.                       -  Minus              *  Multiply
  517.                       /  Divide             &  Arithmetic AND
  518.                       |  Arithmetic OR      ^  Arithmetic Exclusive OR
  519.                       <  Less Than          >  Greater Than
  520.                       =  Assignment         <= Less Than or Equal To
  521.                       == Identical To       >= Greater Than or Equal To
  522.                       && Logical AND        != Not Identical To
  523.                       || Logical OR
  524.  
  525.                       Unary Arithmetic Operators
  526.                       The !, + and - symbols are unary arithmetic
  527.                       operators.  They affect the value associated with
  528.                       the constant or numeric variable which follows the
  529.                       symbol.
  530.  
  531.                       !   invokes the NOT function, causing a boolean
  532.                           True/False evaluation of the expression following
  533.                           the not operator (!).  A non-zero result is
  534.                           evaluated as False;  a zero result is evaluated
  535.                           as True.  For example, IF !EXIST (filename) will
  536.                           perform a set of instructions if the file is not
  537.                           found.
  538.  
  539.                       +   is optional on all numeric values, and implies
  540.                           normal interpretation of the value.
  541.  
  542.                       -   causes a numeric value to be negated, transform-
  543.                           ing a positive value to a negative value, or a
  544.                           negative value to a positive one.
  545.  
  546.                       Binary Arithmetic Operators
  547.                       The + and - signs also may be binary operators.
  548.  
  549.                       +   Addition
  550.                       -   Subtraction
  551.                       *   Multiplication
  552.                       /   Division
  553.                       &   Arithmetic AND function;  the two operands are
  554.                           ANDed bit by bit to produce the resultant numeric
  555.                           value.
  556.                       |   Arithmetic OR function;  performs an inclusive OR
  557.                           on the operands.
  558.                       ^   Performs an arithmetic exclusive OR of the two
  559.                           operands.
  560.  
  561.  
  562.  
  563.  
  564.  
  565.                                               - 9 -
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.                       Binary String Operators
  573.                       The + sign also is a binary string operator.
  574.                       Separating two string values, either literal or
  575.                       variable, causes the catenation of the two strings to
  576.                       form the resultant string value.
  577.  
  578.                       Relational Operators
  579.                       Relational operators, also called logical operators,
  580.                       are used in the IF directive to test the relation
  581.                       between numeric or string variables.  When comparing
  582.                       strings, the operation is not case sensitive;  that
  583.                       is, 'abc' is equivalent to 'ABC'.  The result of a
  584.                       relational operation is either True (any non-zero
  585.                       result) or False (a zero result).
  586.  
  587.                       For example:
  588.  
  589.                       > TYPE = 'BEETLE'
  590.                       > IF MAKER == 'FORD' && TYPE == 'MUSTANG'
  591.  
  592.                       yields a False value, while:
  593.  
  594.                       > IF (ROW >= 24) || (COLUMN >= 79)
  595.                       > GOTO CONTINUE
  596.                       > ENDIF
  597.  
  598.                       yields a True value when you reach row 25 or column
  599.                       80 of the screen.  Note:  Screen coordinates are zero
  600.                       relative.  That is, the point 0,0 defines the top
  601.                       left corner.
  602.  
  603.                       File Transfer Errorlevel Codes
  604.  
  605.                       These codes are returned to the Script file and can
  606.                       be used for error processing at an ONERR label.  For
  607.                       additional information, refer to the ERRORLEVEL,
  608.                       ERRORTEXT, GETERRORTEXT(), IF(), and ONERR system
  609.                       variables, directives and functions.
  610.  
  611.                          Code           Type Of Error
  612.                          0              None
  613.                          1              Timeout
  614.                          2              Line failure (Retry count expired
  615.                                         or loss of carrier)
  616.                          3              Operator cancel
  617.                          4              Remote cancel
  618.                          5              DOS error
  619.                          6              Expression evaluation error
  620.  
  621.                       Variable Names
  622.                       Variable names can contain only alphanumeric
  623.                       characters (A-Z, 0-9) and must begin with an alpha
  624.                       character (A-Z).  Softerm is case insensitive when
  625.                       searching for variable names;  there is no
  626.  
  627.  
  628.  
  629.                                              - 10 -
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.                       distinction between lower case and upper case.
  637.                       Thus, number and NUMBER refer to the same variable.
  638.                       Softerm decides that a string refers to a variable
  639.                       name rather than a literal string by whether or not
  640.                       it is enclosed in quotation marks.
  641.  
  642.                       System Variables and Reserved Names
  643.                       Softerm includes special variables which allow you
  644.                       to access system information from within script
  645.                       files for use in expressions.
  646.  
  647.                       Important:  These names are reserved for use by
  648.                       Softerm and must not be used as variable names.
  649.                       Very unpredictable results can occur.
  650.                       Assignable Predefined System Variables
  651.                       These system variables can be used on the left side
  652.                       of an equality and set to a valid value.  For
  653.                       example:
  654.  
  655.                       > DATABITS = 7
  656.                       BAUD         Numeric variable which can be set to a
  657.                                    valid baud rate in the range 50 through
  658.                                    57600, such as:  > BAUD = 9600
  659.  
  660.                       DATABITS     Numeric variable which can be set to a
  661.                                    value in the range 7 through 8, such
  662.                                    as:  > DATABITS = 7
  663.  
  664.                       ESCAPE       Text variable which defines the lead-in
  665.                                    character to be used.  This variable
  666.                                    defaults to the tilde (~) character.
  667.                                    Additional information is available in
  668.                                    the Inserting Special Functions heading
  669.                                    above.
  670.  
  671.                       PARITY       Numeric variable which can be set to
  672.                                    one of the following values:  NONE,
  673.                                    ODD, EVEN, MARK, SPACE, such as:  >
  674.                                    PARITY = NONE
  675.  
  676.                       RXPACING     Numeric variable which can be set to
  677.                                    one of the following values:   NONE,
  678.                                    XON_XOFF, DTR, RTS, such as:          >
  679.                                    RXPACING = XON_XOFF
  680.  
  681.                       SPEED        Numeric variable which can be set to a
  682.                                    value in the range 0 through 255
  683.                                    milliseconds, such as:  > SPEED = 25
  684.  
  685.                                    The default value is 0.  The SPEED
  686.                                    variable defines a transmit character
  687.                                    delay which allows a delay between
  688.                                    characters transmitted on the
  689.                                    communications line.  This variable
  690.  
  691.  
  692.  
  693.                                              - 11 -
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.                                    could be used when the host computer is
  701.                                    not able to accept characters as fast
  702.                                    as the actual line speed allows.
  703.  
  704.                       STOPBITS     Numeric variable which can be set to 1
  705.                                    or 2.
  706.  
  707.                       TIMEOUT      Numeric variable which can be set to a
  708.                                    value in the range 0 through 65535
  709.                                    seconds.  The default value is 15.  The
  710.                                    TIMEOUT variable specifies the delay
  711.                                    tolerated before cancelling a DIAL or
  712.                                    XMIT_WAIT operation.  A value of 0
  713.                                    indicates that there is an unlimited
  714.                                    timeout period.
  715.  
  716.                       TXPACING     Numeric variable which can be set to
  717.                                    one of the following values:  NONE,
  718.                                    XON_XOFF, XON_XOFF_PAIRS, CTS, DSR, DCD
  719.  
  720.                       Read-Only Predefined System Variables
  721.                       These system variables are not user-settable.
  722.                       Instead, they are updated as required and, as a
  723.                       general rule, are used in conditional processing.
  724.                       For example:
  725.  
  726.                       > IF ERRORLEVEL == 3
  727.                       CONNECT     Logical variable which may be tested
  728.                                   TRUE or FALSE indicating if a connection
  729.                                   currently is established.
  730.  
  731.                       CTS         Numeric variable which may be used to
  732.                                   set TXPACING, such as:  > TXPACING = CTS
  733.  
  734.                       DATE        String variable that holds the current
  735.                                   date in MM/DD/YY format when referenced.
  736.  
  737.                       DAY         Numeric variable that holds the current
  738.                                   day (1-31).
  739.  
  740.                       DCD         Numeric variable which may be used to
  741.                                   set TXPACING, such as:  > TXPACING = DCD
  742.  
  743.                       DSR         Numeric variable which may be used to
  744.                                   set TXPACING, such as:  > TXPACING = DSR
  745.  
  746.                       DTR         Numeric variable which may be used to
  747.                                   set RXPACING, such as:  > RXPACING = DTR
  748.  
  749.                       ERRORCODE   Numeric variable that contains the error
  750.                                   value of the last function that
  751.                                   terminated with a serious error.  This
  752.                                   variable will be set correctly only
  753.                                   during ONERR processing.
  754.  
  755.  
  756.  
  757.                                              - 12 -
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.                       ERRORLEVEL  Numeric variable in the range 0 through
  765.                                   6 which contains the Errorlevel Code
  766.                                   (discussed above and in the description
  767.                                   of the IF() function).  This variable
  768.                                   will be set correctly only during ONERR
  769.                                   processing.
  770.  
  771.                       ERRORTEXT   Text variable which contains the text
  772.                                   related to the ERRORCODE.  ERRORTEXT may
  773.                                   be displayed using the MESSAGE function.
  774.                                   This variable will be set correctly only
  775.                                   during ONERR processing.
  776.  
  777.                       FALSE       Opposite of TRUE.  An expression which
  778.                                   evaluates to a zero result is FALSE.
  779.  
  780.                       HOUR        Numeric variable that holds the current
  781.                                   hour (0-23)
  782.  
  783.                       MINUTE      Numeric variable that holds the current
  784.                                   minute (0-59).
  785.  
  786.                       MONTH       Numeric variable that holds the current
  787.                                   month (1-12).
  788.  
  789.                       NONE        Numeric variable which may be used to
  790.                                   set TXPACING and RXPACING, such as:  >
  791.                                   RXPACING = NONE
  792.  
  793.                       OFF         Numeric variable with the value of zero.
  794.                                   (False)
  795.  
  796.                       ON          Numeric variable with the value of one.
  797.                                   (True)
  798.  
  799.                       PATH        String variable that holds the full path
  800.                                   of the current directory.
  801.  
  802.                       PORT        Text variable that contains the name of
  803.                                   the Connection Path used by the
  804.                                   currently-running script file.
  805.  
  806.                       RTS         Numeric variable which may be used to
  807.                                   set RXPACING, such as:  > RXPACING = RTS
  808.  
  809.                       RXDATA      Text variable containing the last 255
  810.                                   characters received by the most recent
  811.                                   XMIT_WAIT function
  812.  
  813.                       SECOND      Numeric variable which holds the current
  814.                                   second (0-59)
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.                                              - 13 -
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.                       SESSIONNAME Text variable which holds the name of
  829.                                   the current Session as displayed in the
  830.                                   Session Manager window.
  831.  
  832.                       TIME        String variable that holds the current
  833.                                   time in HH:MM 24-hour format.
  834.  
  835.                       TRUE        Used to test the result of a logical
  836.                                   expression.  An expression which
  837.                                   evaluates to a non-zero result is TRUE.
  838.                                   When it is returned from a function,
  839.                                   TRUE will have the value of 1.
  840.  
  841.                       USERNAME    If Host Mode optional logon processing
  842.                                   is in effect, this string variable holds
  843.                                   the current username of 32 characters,
  844.                                   blank filled.
  845.  
  846.                       WEEKDAY     Numeric variable which contains the day
  847.                                   of the week in the form 0 (Sunday)
  848.                                   through 6 (Saturday).
  849.  
  850.                       XON_XOFF    Numeric variable which may be used to
  851.                                   set TXPACING and RXPACING, such as:  >
  852.                                   TXPACING = XON_XOFF
  853.  
  854.                       XON_XOFF_PAIRS   Numeric variable which may be used
  855.                                        to set TXPACING, such as:
  856.                                        > TXPACING = XON_XOFF_PAIRS
  857.  
  858.                       YEAR        Numeric variable that holds the current
  859.                                   year.
  860.                       Script Functions and Directives
  861.                       Softerm file transfers are controlled by the
  862.                       following directives and functions which may require
  863.                       additional parameters:
  864.  
  865.                       (semi-colon)      Comment
  866.                       : (colon)         Label (name) a command sequence
  867.                                         location
  868.  
  869.                       AUTOANSWER()      Enable and disable an auto-dial
  870.                                         modem's Auto-Answer mode
  871.  
  872.                       BREAK()           Transmit a communications break
  873.                                         signal
  874.  
  875.                       CANCEL            Cancel the operation of a script
  876.                                         file
  877.  
  878.                       CHAIN()           Transfer script operation to a new
  879.                                         script file
  880.  
  881.                       CHDIR() or CD()   Change default directory
  882.  
  883.  
  884.  
  885.                                              - 14 -
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.                       CHRTOVAL()        Returns the numeric value of any
  893.                                         ASCII character (for example, '1'
  894.                                         is returned as 49)
  895.  
  896.                       CLOSE()           Close a specified open disk file
  897.  
  898.                       CLOSEALL()        Close all open files
  899.  
  900.                       CONVERSE()        Exit to online operation
  901.  
  902.                       COPY()            Copy a file
  903.  
  904.                       DELETE()          Delete a file
  905.  
  906.                       DIAL()            Establish a communications
  907.                                         connection
  908.  
  909.                       ELSE              Alternate conditional processing
  910.  
  911.                       END               End of script file
  912.  
  913.                       ENDIF             End conditional processing
  914.  
  915.                       EXIST()           Check for the existence of a
  916.                                         particular file
  917.  
  918.                       EXIT              Terminate the current script file
  919.                                         and the current runtime session.
  920.  
  921.                       FINDLINE()        Search an open file for a
  922.                                         particular text string
  923.  
  924.                       FIRSTFILE()       Return information about the first
  925.                                         file found in the given  path/file
  926.                                         name template
  927.  
  928.                       FIXLENGTH()       Sets the length of a text string
  929.                                         by padding with spaces or by
  930.                                         truncating
  931.  
  932.                       GETERRORTEXT()    Converts any numeric value to its
  933.                                         related error text (if there is
  934.                                         any).  In particular, this would
  935.                                         be used to create the error text
  936.                                         for a result code which is
  937.                                         returned by a function.
  938.  
  939.                       GETLENGTH()       Returns the numeric value of the
  940.                                         length of a text string
  941.  
  942.                       GOTO or JUMP      Go to a Label
  943.  
  944.                       HANGUP()          Disconnect, lower DTR
  945.  
  946.  
  947.  
  948.  
  949.                                              - 15 -
  950.  
  951.  
  952.  
  953.  
  954.  
  955.  
  956.                       HOST()            Initiate a Host mode -- unattended
  957.                                         interaction
  958.  
  959.                       IF                Begin conditional processing
  960.  
  961.                       INPUT()           Accept operator text input to the
  962.                                         script
  963.  
  964.                       LOG()             Begin logging
  965.  
  966.                       LOWER()           Convert a string to all lower-case
  967.  
  968.                       MESSAGE()         Displays a message in the progress
  969.                                         frame window, no wait
  970.  
  971.                       MKDIR()           Create a disk directory
  972.  
  973.                       NEXTFILE()        Returns an information text string
  974.                                         for the next file matching the
  975.                                         file name template specified in a
  976.                                         FIRSTFILE function
  977.  
  978.                       NOLOG()           End logging
  979.  
  980.                       ON()              Branch in a Script file based on a
  981.                                         received value
  982.  
  983.                       ONERR             Use this directive to provide a
  984.                                         label to which Script processing
  985.                                         will be redirected in the event of
  986.                                         a serious error which otherwise
  987.                                         would cause Script operation to
  988.                                         terminate
  989.  
  990.                       OPENNEW()         Create and open a new disk file
  991.  
  992.                       OPENOLD()         Open an existing disk file
  993.  
  994.                       PAUSE()           Delay n seconds
  995.  
  996.                       PROMPT()          Displays an information message
  997.                                         box until cancelled by the
  998.                                         operator
  999.  
  1000.                       READ()            Returns a text string from an open
  1001.                                         file
  1002.  
  1003.                       READLINE()        Returns a line of text from an
  1004.                                         open file
  1005.  
  1006.                       RECEIVE()         Transfer a file from a host to
  1007.                                         your PC
  1008.  
  1009.                       RENAME()          Rename a file
  1010.  
  1011.  
  1012.  
  1013.                                              - 16 -
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.                       RESUME            Resume operation after error
  1021.  
  1022.                       RETRY             Retry last command
  1023.  
  1024.                       RSTATTR()         Reset file attributes
  1025.  
  1026.                       SEND()            Transfer a file from your PC to a
  1027.                                         host
  1028.  
  1029.                       SETATTR()         Set a file's attributes
  1030.  
  1031.                       SETBOF()          During file operations, sets the
  1032.                                         position of the internal file
  1033.                                         pointer to the beginning of the
  1034.                                         file
  1035.  
  1036.                       SETEOF()          During file operations, sets the
  1037.                                         position of the internal file
  1038.                                         pointer to the end of the file
  1039.  
  1040.                       SKIP()            During file operations, sets the
  1041.                                         position of the internal file
  1042.                                         pointer relative to the current
  1043.                                         file position
  1044.  
  1045.                       STRFIND1()        Returns the numeric position of
  1046.                                         the start of a specified text
  1047.                                         string within a text string
  1048.  
  1049.                       STRFIND2()        Returns the numeric position of
  1050.                                         any character from a specified
  1051.                                         text list within a text string
  1052.  
  1053.                       STRGET1()         Extracts a text string from a text
  1054.                                         string by length
  1055.  
  1056.                       STRGET2()         Extracts a text string from a text
  1057.                                         string terminated by a specific
  1058.                                         terminator character from a text
  1059.                                         string
  1060.  
  1061.                       STRPUT()          Replaces a text substring within a
  1062.                                         text string
  1063.  
  1064.                       STRTOVAL()        Returns the numeric value
  1065.                                         representing an ASCII numeric text
  1066.                                         string (for example, '456' is
  1067.                                         returned as 456)
  1068.  
  1069.                       UPPER()           Convert a string to all upper-case
  1070.  
  1071.                       VALTOCHR()        Returns the ASCII character
  1072.                                         representing a numeric value (for
  1073.                                         example, 49 is returned as '1')
  1074.  
  1075.  
  1076.  
  1077.                                              - 17 -
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.                       VALTOSTR()        Returns the ASCII numeric text
  1085.                                         string representing a numeric
  1086.                                         value
  1087.  
  1088.                       VCLEAR()          Clear all variables
  1089.  
  1090.                       VDEFINED()        Check if a variable has been
  1091.                                         defined
  1092.  
  1093.                       VDELETE()         Clear a particular variable
  1094.  
  1095.                       WAIT()            Wait for an event and return a
  1096.                                         code
  1097.  
  1098.                       WRITE()           Writes a text string to an open
  1099.                                         file
  1100.  
  1101.                       WRITELINE()       Writes a line of text to an open
  1102.                                         file
  1103.  
  1104.                       XMIT_WAIT()       Transmit a string, wait for a
  1105.                                         reply
  1106.  
  1107.                       Script Window Control Functions
  1108.                       These functions control the separate window which may
  1109.                       be displayed by a script file.  They are explained at
  1110.                       the end of this chapter:
  1111.  
  1112.                       WATCH()           Display script commands and current
  1113.                                         file and directory names in the
  1114.                                         script window
  1115.  
  1116.                       WINDOWPOS()       Set the upper left corner of a
  1117.                                         script file window
  1118.  
  1119.                       WINDOWPRMS()      Set menu and display options to be
  1120.                                         used by a script window
  1121.  
  1122.                       WINDOWSHOW()      Display a user-defined script
  1123.                                         window
  1124.  
  1125.                       WINDOWSIZE()      Set the size of the client area of
  1126.                                         a script file window
  1127.  
  1128.                       WINDOWTITLE()     Provide a title for a script file
  1129.                                         window
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.                                              - 18 -
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.                       Script Functions Descriptions
  1149.  
  1150.                       AUTOANSWER (arg1)
  1151.                       Function:  Enable or Disable an auto-dial modem's
  1152.                                  Auto-Answer mode
  1153.                       Syntax:
  1154.  
  1155.                          > AUTOANSWER (on)
  1156.                          > AUTOANSWER (off)
  1157.  
  1158.                       If this command is processed when a connection has
  1159.                       already been established, an error message similar
  1160.                       to the following will be generated:  "Can not Change
  1161.                       Mode while Connected".
  1162.  
  1163.                       BREAK()
  1164.                       Function: Send a communications break signal of 255
  1165.                                 milliseconds  duration
  1166.                       Syntax:
  1167.  
  1168.                            > BREAK()
  1169.  
  1170.                       BREAK (arg1)
  1171.                       Function: Send a communications break signal for a
  1172.                                 specified number of seconds
  1173.                       Syntax:
  1174.  
  1175.                            > BREAK (seconds)
  1176.  
  1177.                       The argument may be a numeric value in the range 1 -
  1178.                       9 which specifies of the break signal duration in
  1179.                       seconds.
  1180.  
  1181.                       CANCEL
  1182.                       Function: Cancel further script file processing
  1183.                       Syntax:
  1184.  
  1185.                            > CANCEL
  1186.  
  1187.                       This directive usually is used in combination with
  1188.                       the ONERR directive and IF ERRORLEVEL conditional
  1189.                       processing when it is desired to terminate
  1190.                       processing of the script file due to the type of
  1191.                       error encountered.
  1192.  
  1193.                       The current script file and log file are closed when
  1194.                       a CANCEL command is processed.
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.                                              - 19 -
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.                       CHAIN (arg1)
  1213.                       Function: Terminate the operation of the current
  1214.                                 script file and start another
  1215.                       Syntax:
  1216.  
  1217.                            > CHAIN (path_scriptname)
  1218.  
  1219.                       where:
  1220.  
  1221.                       PATH_SCRIPTNAME is the text string or defined
  1222.                       variable providing the location and name of the
  1223.                       script file to run.
  1224.  
  1225.                       Example:
  1226.  
  1227.                       > CHAIN ('c:\softerm\scripts\sethost.scr')
  1228.  
  1229.                       Use when a single script file cannot contain all the
  1230.                       commands required, or it is desired to segment the
  1231.                       operation of multiple operations.  All file transfer
  1232.                       variables including the variable heap, error
  1233.                       processing retry count, transmit character delay,
  1234.                       and timeout value are unchanged after the CHAIN.
  1235.                       Logging will remain enabled if active.
  1236.  
  1237.                       Wildcard characters are not allowed in the file name
  1238.                       entered.  When a CHAIN command is used, if the
  1239.                       specified script file does not exist, an error
  1240.                       message is displayed;  the command is cancelled;
  1241.                       and operation of the current script file is
  1242.                       terminated.
  1243.  
  1244.                       CHDIR (arg1) and CD (arg1)
  1245.                       Function: Set a new default directory path
  1246.                       Syntax:
  1247.  
  1248.                            > CD (pathname)
  1249.  
  1250.                       where:
  1251.  
  1252.                       PATHNAME is the text string or defined variable
  1253.                       providing the drive and directory to which to
  1254.                       change.
  1255.  
  1256.                       Example:
  1257.  
  1258.                                    > CD ('s:\database')
  1259.  
  1260.                       The new default directory including a drive
  1261.                       specifier and directory path is entered as an
  1262.                       argument on the command line.  File names entered
  1263.                       for file transfer commands may include a drive
  1264.                       specifier and a complete directory path from the
  1265.                       root directory of the drive.  If no directory path
  1266.  
  1267.  
  1268.  
  1269.                                              - 20 -
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.                       is specified in a file name, the current default
  1277.                       directory path will be used.  If the directory path
  1278.                       specified in a file name does not begin with the
  1279.                       root directory, Softerm assumes the directory path
  1280.                       specified begins with the current default directory.
  1281.  
  1282.                       CHRTOVAL (arg1)
  1283.                       Function: Returns the numeric value of any ASCII
  1284.                                 character (for example, '1' is returned as
  1285.                                 49)
  1286.                       Syntax:
  1287.  
  1288.                                    > CHRTOVAL (ascii)
  1289.  
  1290.                       where:
  1291.  
  1292.                         ASCII is the ASCII character.
  1293.  
  1294.                       Example:
  1295.  
  1296.                       > NUM_VAL = CHRTOVAL ('Z')
  1297.  
  1298.                       The numeric variable NUM_VAL will contain the
  1299.                       decimal value 90.
  1300.  
  1301.                       The CHRTOVAL function can be used to extract control
  1302.                       codes from text variables.  For instance, a Ctrl A
  1303.                       would be returned as 1.  CHRTOVAL also can be used
  1304.                       to compute checksums (the sum of the ASCII values of
  1305.                       each character in a string).
  1306.  
  1307.                       CLOSE (arg1)
  1308.                       Function: Close an open file
  1309.                       Syntax:
  1310.  
  1311.                            > CLOSE (file_handle)
  1312.  
  1313.                       where:
  1314.  
  1315.                       FILE_HANDLE must be the name of a variable that
  1316.                       contains the handle returned by a previous file open
  1317.                       function
  1318.  
  1319.                       CLOSEALL()
  1320.                       Function: Close all open files
  1321.                       Syntax:
  1322.  
  1323.                            > CLOSEALL()
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.                                              - 21 -
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.                       CONVERSE (arg1)
  1341.                       Function: Return to the online terminal operation
  1342.                                 mode;  stopping the current script file
  1343.                       Syntax:
  1344.  
  1345.                            > CONVERSE (initial_string)
  1346.  
  1347.                       where:
  1348.  
  1349.                       INITIAL_STRING is an optional string (maximum 35
  1350.                       characters) which may be entered as initial keyboard
  1351.                       input to the online terminal mode.
  1352.  
  1353.                       Example:
  1354.  
  1355.                            > CONVERSE ([CR])
  1356.  
  1357.                       The CONVERSE command is useful when an immediate
  1358.                       return to the online terminal mode is required from
  1359.                       a script file.  The CONVERSE command is not valid
  1360.                       when used in a script file run when terminal mode is
  1361.                       not available.
  1362.  
  1363.                       COPY (arg1,arg2,arg3)
  1364.                       Function: Copy a file
  1365.                       Syntax:
  1366.  
  1367.                            > COPY (source,dest,if_exist)
  1368.  
  1369.                       where:
  1370.  
  1371.                       SOURCE is the source path and file name text string.
  1372.                       DEST is the destination path and file name text
  1373.                       string.
  1374.                       IF_EXIST is the option to use if a file with the
  1375.                       DEST name already exists.  The options are:
  1376.  
  1377.                       Replace     Overwrite the existing file with the new
  1378.                                   file.
  1379.                       Append      Add the contents of the new file to the
  1380.                                   end of the existing file.  This
  1381.                                   generally is not a appropriate option to
  1382.                                   use with binary files.
  1383.                       Fail        Cancel the Copy operation.  This is the
  1384.                                   default.
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.                                              - 22 -
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.                       Example:
  1405.  
  1406.                       > COPY ('c:\softerm\my.mdb',
  1407.                              's:\softerm\public\special.mdb',replace)
  1408.  
  1409.                       or
  1410.  
  1411.                       > SV3 = 'c:\softerm\my.mdb'
  1412.                       > SV4 = 's:\softerm\public\special.mdb'
  1413.                       > COPY (SV3,SV4,)
  1414.  
  1415.                       DELETE (arg1)
  1416.                       Function: Delete a file from the current or
  1417.                                 specified directory
  1418.                       Syntax:
  1419.  
  1420.                            > DELETE (path_filename)
  1421.  
  1422.                       where:
  1423.  
  1424.                       PATH_FILENAME is the text string or defined variable
  1425.                       providing the location and name of the file to
  1426.                       delete.
  1427.  
  1428.                       Example:
  1429.  
  1430.                            > DELETE ('c:\softerm\softemp.999')
  1431.  
  1432.                       If no drive or directory path is entered, the file
  1433.                       is deleted from the current directory.  You can use
  1434.                       the wildcard characters (?) and (*) in the file name
  1435.                       and in the extension.
  1436.  
  1437.                       If the file does not exist, no error is reported and
  1438.                       command processing will continue.  All other DOS
  1439.                       errors will cause error processing to be performed.
  1440.  
  1441.                       DIAL (arg1,arg2,arg3,arg4)
  1442.                       Function: Establish a communications connection
  1443.                       Syntax:
  1444.  
  1445.                            > DIAL (handshake_trans,phone_num1,telnet_id,phone_num2)
  1446.  
  1447.                       Note:  The number of arguments and their types depend
  1448.                       on the current connection path type and the
  1449.                       applicable Admittance Data dialog.
  1450.  
  1451.                       where:
  1452.  
  1453.                       HANDSHAKE_TRANS is a string which will be
  1454.                       transmitted automatically when a connection is made.
  1455.                       If no string is entered, this argument defaults to
  1456.                       either:
  1457.  
  1458.  
  1459.  
  1460.  
  1461.                                              - 23 -
  1462.  
  1463.  
  1464.  
  1465.  
  1466.  
  1467.  
  1468.                       o The string used by a previous DIAL command, or
  1469.                       o The Handshake Transmission string as defined in
  1470.                         the Admittance Data configuration for the current
  1471.                         Session if no previous DIAL command has been
  1472.                         issued.
  1473.  
  1474.                       PHONE_NUM is the Phone Number or equivalent, such as
  1475.                       a Called DTE Address or Service Name.  If no string
  1476.                       is entered, this argument defaults to either:
  1477.  
  1478.                       o The string used by a previous DIAL command, or
  1479.                       o The field which precedes the Handshake
  1480.                         Transmission field defined in the Admittance Data
  1481.                         configuration for the current Session if no
  1482.                         previous DIAL command has been issued.
  1483.                       Note:  If the Admittance Data configuration has only
  1484.                       the Handshake Transmission field, the DIAL command
  1485.                       will have only one argument.
  1486.  
  1487.                       TELNET_ID is the Telephone Network ID string.  If no
  1488.                       string is entered, this argument defaults to either:
  1489.                       o The string used by a previous DIAL command, or
  1490.                       o The Telephone Network profile defined in the
  1491.                         Admittance Data configuration for the current
  1492.                         Session if no previous DIAL command has been
  1493.                         issued.
  1494.                       Note:  If the current Admittance Data configuration
  1495.                       does not have a Telephone Network profile field,
  1496.                       this argument is not applicable.
  1497.  
  1498.                       PHONE_NUM2 is the second telephone number (or
  1499.                       equivalent).  For example, the IBM ACS connection
  1500.                       lets you dial by specifying the CBX Datagroup and
  1501.                       the Account ID.  The DIAL() function might resemble:
  1502.  
  1503.                            > DIAL (,CBXData_Group,,Accnt_ID)
  1504.  
  1505.                       This example does not specify a handshake
  1506.                       transmission or a telephone network profile name.
  1507.  
  1508.                       Important
  1509.                       If an argument is not specified, DIAL will attempt
  1510.                       to make the connection using either the value
  1511.                       contained in the current Admittance Data
  1512.                       configuration field or the last value which was
  1513.                       used, whichever is more current.  To ensure no value
  1514.                       is used for an argument, place a null-length string
  1515.                       in the argument's position.  For example, the
  1516.                       following command would dial the Softronics'
  1517.                       Customer Service BBS without transmitting an initial
  1518.                       string and without using a Telephone Network ID:
  1519.  
  1520.                       > DIAL ('','17195939530','')
  1521.  
  1522.  
  1523.  
  1524.  
  1525.                                              - 24 -
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.  
  1532.                       The DIAL function uses the values of the current
  1533.                       TIMEOUT and RETRIES parameters.  For example, if
  1534.                       TIMEOUT is set to 45 seconds and RETRIES is set to
  1535.                       8, the DIAL function will attempt to make the
  1536.                       connection 8 times and will wait 45 seconds each
  1537.                       time before cancelling the operation.  Note:  Values
  1538.                       for TIMEOUT less than 30 seconds are defaulted to 30
  1539.                       seconds for the DIAL function.
  1540.  
  1541.                       ELSE
  1542.                       Function: Specify alternate conditional processing
  1543.                                 when used in conjunction with a previous
  1544.                                 IF command
  1545.                       Syntax:
  1546.  
  1547.                            > ELSE
  1548.  
  1549.                       If the conditional result of an IF command is true,
  1550.                       all commands following the IF command are processed
  1551.                       until an ELSE or the corresponding ENDIF command is
  1552.                       encountered.  Commands following an ELSE command up
  1553.                       to the corresponding ENDIF command are ignored.
  1554.  
  1555.                       If the conditional result of an IF command is false,
  1556.                       all commands following the IF are ignored until an
  1557.                       ELSE command or ENDIF command is encountered.
  1558.                       Commands following the ELSE command are processed
  1559.                       until the ENDIF command corresponding to the IF
  1560.                       command is reached.
  1561.  
  1562.                       This command is ignored if there is no previous
  1563.                       corresponding IF command.  The following example
  1564.                       demonstrates how the ELSE command is used:
  1565.  
  1566.                       > IF conditional expression
  1567.                       >
  1568.                       >    commands processed if condition is true
  1569.                       >
  1570.                       > ELSE
  1571.                       >
  1572.                       >    commands processed if condition is false
  1573.                       >
  1574.                       > ENDIF
  1575.  
  1576.                       For example:
  1577.  
  1578.                       > IF RESPONSE == 'Y'
  1579.                       > GOTO DO-IT
  1580.                       > ELSE
  1581.                       > NUMVAR = 1
  1582.                       > CHAIN ('NORESP.SCR')
  1583.                       > END
  1584.                       > ENDIF
  1585.  
  1586.  
  1587.  
  1588.  
  1589.                                              - 25 -
  1590.  
  1591.  
  1592.  
  1593.  
  1594.  
  1595.  
  1596.                       END
  1597.                       Function: Terminate the operation of a script file
  1598.                       Syntax:
  1599.  
  1600.                            > END
  1601.  
  1602.                       The current script file and any log file are closed
  1603.                       when an END command is processed.
  1604.  
  1605.                       ENDIF
  1606.                       Function: Terminate the conditional processing of a
  1607.                                 previous corresponding IF statement and
  1608.                                 resume normal command processing
  1609.                       Syntax:
  1610.  
  1611.                            > ENDIF
  1612.  
  1613.                       This command is ignored if there is no previous
  1614.                       corresponding IF command.
  1615.  
  1616.                       EXIST (arg1)
  1617.                       Function: Test for the existence of a file and
  1618.                                 return a TRUE or FALSE result
  1619.                       Syntax:
  1620.  
  1621.                            > EXIST (path_filename)
  1622.  
  1623.                       where:
  1624.  
  1625.                       PATH_FILENAME is the text string or defined variable
  1626.                       providing the location and name of the file for
  1627.                       which you are checking.
  1628.  
  1629.                       If no drive or directory path is entered, the test
  1630.                       is performed in the current directory.
  1631.  
  1632.                       This function usually is used in an IF statement,
  1633.                       such as
  1634.  
  1635.                       > IF EXIST ('v:\database\test.dbf')
  1636.                       > ; do one thing
  1637.                       > ELSE
  1638.                       > ; do something else
  1639.                       > ENDIF
  1640.  
  1641.                       The following example also is valid:
  1642.  
  1643.                       > FILENAME = 'c:\softerm\manual.txt'
  1644.                       > VALUE = EXIST (filename)
  1645.                       > IF VALUE == TRUE
  1646.                       > ...
  1647.                       > ENDIF
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.                                              - 26 -
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.  
  1660.                       EXIT
  1661.                       Function: Terminate the current script file and the
  1662.                                 current runtime session.
  1663.                       Syntax:
  1664.  
  1665.                            > EXIT
  1666.  
  1667.                       This is similar to the END directive, except that
  1668.                       EXIT also terminates the current runtime session.
  1669.  
  1670.                       FINDLINE (arg1,arg2)
  1671.                       Function: Search an open file for a particular text
  1672.                                 string and return a TRUE or FALSE value
  1673.                                 result
  1674.                       Syntax:
  1675.  
  1676.                            > RESULT = FINDLINE (filedef,search_string)
  1677.  
  1678.                       where:
  1679.  
  1680.                       FILEDEF must be the name of a variable that contains
  1681.                       the handle returned by a previous file open
  1682.                       function.
  1683.                       SEARCH_STRING is the text string or the variable
  1684.                       containing the text string to locate.
  1685.  
  1686.                       This function will treat the open file defined by
  1687.                       the file definition variable, FILDEF, as a line-type
  1688.                       file and will search, from the current position of
  1689.                       the pointer in the file, each line of text for the
  1690.                       match string.
  1691.  
  1692.                       If the value of RESULT is TRUE, the position of the
  1693.                       internal file pointer will have been set to the
  1694.                       first character of the line containing the specified
  1695.                       text.
  1696.  
  1697.                       > NAME = 'JONES, JOHN'
  1698.                       > RESULT = FINDLINE (FILDEF,NAME)
  1699.  
  1700.                       On completion of the command, a result code is
  1701.                       returned to the variable RESULT.  A result code of
  1702.                       True means the search was successful;  a False value
  1703.                       indicates that the command was not successful.  If
  1704.                       the returned result is True, the current file
  1705.                       position will be set to the first character of the
  1706.                       text line containing the match string.
  1707.  
  1708.                       The statement:
  1709.  
  1710.                       > IF (FINDLINE(FILDEF,VName)) == FALSE
  1711.  
  1712.                       will search from the current position in the open
  1713.                       file for the value contained in the variable VName.
  1714.  
  1715.  
  1716.  
  1717.                                              - 27 -
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.                       (VName must have been defined by a previous
  1725.                       statement, such as VName = 'Chevrolet', or the value
  1726.                       must have been read into it by a previous READ or
  1727.                       READLINE function).
  1728.  
  1729.                       If the value is not found (the returned value of the
  1730.                       operation is FALSE), you can process an error-
  1731.                       handling or branching routine.  For instance, it
  1732.                       could mean that the value assigned to the variable
  1733.                       VName has been entered incorrectly;  or the internal
  1734.                       file pointer is past the point in the file where the
  1735.                       value assigned to VName is.
  1736.  
  1737.                       FIRSTFILE (arg1,arg2)
  1738.                       Function: Return information about the first file
  1739.                                 found in the given  path/file name
  1740.                                 template
  1741.                       Syntax:
  1742.  
  1743.                             > FIRSTFILE (template,filedef)
  1744.  
  1745.                       where:
  1746.  
  1747.                       TEMPLATE is the file name template text string.
  1748.  
  1749.                       FILEDEF must be the name of a variable to receive a
  1750.                       unique identifier value that will be used as an
  1751.                       argument in any subsequent NEXTFILE functions.
  1752.  
  1753.                       Examples:
  1754.  
  1755.                       > INFOSTRING = FIRSTFILE('C:\*.*',FILDEF)
  1756.                             or
  1757.                       > FILENAME = 'C:\*.*'
  1758.                       > INFOSTRING = FIRSTFILE(FILENAME,FILDEF)
  1759.  
  1760.                       The returned text variable (INFOSTRING) will be a
  1761.                       null length string if no matching file name is found
  1762.                       or will contain a fixed-format text string as
  1763.                       follows:
  1764.  
  1765.                       bytes:
  1766.                       1-12   file name
  1767.                       13     blank
  1768.                       14-21  file size
  1769.                       22     blank
  1770.                       23-30  file date in mm-dd-yy format
  1771.                       31     blank
  1772.                       32-36  file time in hh:mm format
  1773.                       37     blank
  1774.                       38     A attribute character, archived file
  1775.                       39     D attribute character, file name is a
  1776.                              directory
  1777.  
  1778.  
  1779.  
  1780.  
  1781.                                              - 28 -
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.                       40     V attribute character, file name is a volume
  1789.                              name
  1790.                       41     S attribute character, system file
  1791.                       42     H attribute character, hidden file
  1792.                       43     R attribute character, read-only file
  1793.  
  1794.                       The internal resources allocated for the unique
  1795.                       identifier are released automatically under the
  1796.                       following circumstances:
  1797.  
  1798.                       1. When no file is available for this FIRSTFILE
  1799.                          function
  1800.                       2. When no more files are available to a subsequent
  1801.                          NEXTFILE function
  1802.                       3. By processing a CLOSE(filedef) function
  1803.                       4. By processing a CLOSEALL() function
  1804.  
  1805.                       FIXLENGTH (arg1,arg2)
  1806.                       Function: Sets the length of a text string by
  1807.                                 padding with spaces or by truncating
  1808.                       Syntax:
  1809.  
  1810.                             > FIXLENGTH (source_string,length)
  1811.  
  1812.                       where:
  1813.  
  1814.                       SOURCE_STRING is the source text string.
  1815.  
  1816.                       LENGTH is the numeric value of the length.
  1817.  
  1818.                       Examples:
  1819.  
  1820.                       > SRCSTR = 'Enter File Name"
  1821.                       > OUTPUTSTRING = FIXLENGTH (SRCSTR,20) + ':'
  1822.                             or
  1823.                       > LEN = 20
  1824.                       > OUTPUTSTRING = FIXLENGTH (SRCSTR,LEN)
  1825.  
  1826.                       GETERRORTEXT (arg1)
  1827.                       Function: Converts any numeric value to its related
  1828.                                 error text (if there is any)
  1829.                       Syntax:
  1830.  
  1831.                             > GETERRORTEXT (numeric)
  1832.  
  1833.                       where:
  1834.  
  1835.                       NUMERIC can be any numeric value, although the
  1836.                       function is designed primarily to use the result
  1837.                       codes which are returned by a script function.
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.                                              - 29 -
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.                       Examples:
  1853.  
  1854.                       > RESULT = OPENNEW ('TEST.DOC',FILEDEF)
  1855.                       > IF RESULT != 0  ; If file creation failed
  1856.                         ; We'll display the reason
  1857.                       > MESSAGE (GETERRORTEXT (RESULT))
  1858.                       > ENDIF
  1859.                          or
  1860.                       > NUMERIC = 63
  1861.                       > MESSAGE (GETERRORTEXT (NUMERIC))
  1862.  
  1863.                       Important
  1864.                       1.  Not all numeric values have associated error
  1865.                           text.
  1866.  
  1867.                       2.  Unlike the ERRORLEVEL and ERRORTEXT variables,
  1868.                           this function may be used during local error
  1869.                           checking, rather than only during ONERR
  1870.                           processing.
  1871.  
  1872.                       3.  Although the command:
  1873.  
  1874.                       > OPENNEW ('TEST.DOC',FILEDEF)
  1875.  
  1876.                         is perfectly legal, you'll notice that there is no
  1877.                         variable to hold a returned result code.  It is
  1878.                         not possible to verify the success or failure of
  1879.                         the call.
  1880.  
  1881.                       GETLENGTH (arg1)
  1882.                       Function: Returns the numeric value of the length of
  1883.                                 a text string
  1884.                       Syntax:
  1885.  
  1886.                            > GETLENGTH (source_string)
  1887.  
  1888.                       where:
  1889.  
  1890.                       SOURCE_STRING is the source text string.
  1891.  
  1892.                       Example:
  1893.  
  1894.                       > SRCSTR =  'Softerm Modular -- The best choice
  1895.                                   for Windows and OS/2'
  1896.                       > STRLENGTH = GETLENGTH (SRCSTR)
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.                                              - 30 -
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.                       GOTO label
  1917.                       Function: Transfer command processing to the command
  1918.                                 immediately following a specified Label
  1919.                       Syntax:
  1920.  
  1921.                            > GOTO Label
  1922.  
  1923.                       Label corresponds to the name specified in a Label.
  1924.                       A Label name must begin with an alpha character and
  1925.                       only the first 10 characters are significant.
  1926.  
  1927.                       GOTOs may occur in either a forward or backward
  1928.                       direction, and processing will continue with the
  1929.                       first command following a label whose name matches
  1930.                       the GOTO command label.  If no label is found with a
  1931.                       matching name, operation is cancelled.
  1932.  
  1933.                       Note:  A Label is written in the form:
  1934.  
  1935.                       > Label_Name:
  1936.  
  1937.                       The GOTO command will cancel all conditional
  1938.                       processing when used with IF, ELSE, and ENDIF
  1939.                       commands.
  1940.  
  1941.                       GOTO and Processing Speed
  1942.                       All GOTO operations cause the script file to return
  1943.                       to the beginning and conduct a forward search for
  1944.                       the Label.  This, naturally, causes a slowdown of
  1945.                       the processing time.
  1946.  
  1947.                       You may speed up operation significantly by
  1948.                       rearranging the order of the script file so that all
  1949.                       initial setup operations are actually placed at the
  1950.                       end of the file, and placing a GOTO LabelName (such
  1951.                       as BEGIN) at the very beginning and a GOTO
  1952.                       OtherLabelName at the end of the initialization
  1953.                       sequence returning processing to the physical
  1954.                       beginning of the file, such as:
  1955.  
  1956.                       > GOTO Begin
  1957.                       > RealOperations:
  1958.                             .
  1959.                       Sequence of operations involving numerous GOTO
  1960.                       commands
  1961.                             .
  1962.                       > Begin:
  1963.                             .
  1964.                       Initialization routine
  1965.                             .
  1966.                       > GOTO RealOperations
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.                                              - 31 -
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.                       HANGUP()
  1981.                       Function: End the current communications connection
  1982.                       Syntax:
  1983.  
  1984.                            > HANGUP()
  1985.  
  1986.                       The DTR (data terminal ready) control signal is low-
  1987.                       ered and Softerm waits 3 seconds for the connection
  1988.                       to be broken.  Then Softerm continues processing of
  1989.                       a script file with the next command.  Note:  When
  1990.                       used with a Communications Server, the connection to
  1991.                       the service is broken.
  1992.  
  1993.                       Note:  After a HANGUP command has been processed,
  1994.                       the DTR control signal remains low until a
  1995.                       communications command, such as DIAL or XMIT is
  1996.                       processed.
  1997.  
  1998.                       HOST (arg1,arg2,arg3,arg4,arg5)
  1999.                       Function: Initiate operation of a host mode
  2000.                                 environment.  Note:  This function is
  2001.                                 described in the chapter, Host Mode.
  2002.                       Syntax:
  2003.  
  2004.                            > HOST (idletime,maxtime,term_on,force,script)
  2005.  
  2006.                       where:
  2007.  
  2008.                       IDLETIME is a numeric value in minutes that defines
  2009.                       the maximum time which can elapse at the READY
  2010.                       prompt without input from the caller.  A zero value
  2011.                       allows unlimited idle time.
  2012.  
  2013.                       MAXTIME is a numeric value in minutes that defines
  2014.                       the maximum connect time allowed per connection.  A
  2015.                       zero value allows unlimited connect time per
  2016.                       connection.
  2017.  
  2018.                       TERM_ON defines the condition under which the Host
  2019.                       mode environment will be automatically terminated.
  2020.                       Available options are:
  2021.  
  2022.                       NONE (default)
  2023.                       IDLE
  2024.                       MAXTIME
  2025.                       NOCARRIER
  2026.  
  2027.                       FORCE defines whether the Host mode security feature
  2028.                       will be forced if the Host mode was initiated when a
  2029.                       communications connection already existed.
  2030.                       Available options are:
  2031.  
  2032.                       NO (default)
  2033.                       YES
  2034.  
  2035.  
  2036.  
  2037.                                              - 32 -
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.                       SCRIPT is a text string that defines a script file
  2045.                       to be run whenever a new communications connection
  2046.                       is established.
  2047.  
  2048.                       The following are valid HOST() commands:
  2049.  
  2050.                       > HOST (30,,,)
  2051.                       > HOST (0,,,"C:\SOFTERM\SCR\HOST.SCR")
  2052.                       > HOST (0,NOCARRIER,YES,)
  2053.  
  2054.                       IF (expression)
  2055.                       Function: Provide conditional processing within a
  2056.                                 script file by testing for a True or False
  2057.                                 evaluation of an expression
  2058.                       Syntax:
  2059.  
  2060.                            > IF expression
  2061.  
  2062.                       Variables, constants, literals and functions may be
  2063.                       included in the expression to be evaluated.
  2064.  
  2065.                       Softerm provides a special variable called
  2066.                       ERRORLEVEL that allows you to test for any error
  2067.                       conditions which may occur during the operation of a
  2068.                       script file.  This is a reserved variable name that
  2069.                       represents the completion state of the last command
  2070.                       to be processed.  The possible values of the
  2071.                       ERRORLEVEL variable are:
  2072.  
  2073.                     Errorlevel    Type of Error
  2074.                          0        None
  2075.                          1        Timeout
  2076.                          2        Line Failure (Retry count expired or
  2077.                                   loss of carrier)
  2078.                          3        Operator Cancel
  2079.                          4        Remote Cancel
  2080.                          5        DOS Error
  2081.                          6        Expression evaluation error
  2082.  
  2083.                       The ERRORLEVEL variable is used in conjunction with
  2084.                       the ONERR directive to provide an error processing
  2085.                       routine when an error occurs during the processing
  2086.                       of any command.  The ERRORLEVEL variable always
  2087.                       contains the value of the error code from the
  2088.                       previous command.  If the ONERR directive is not
  2089.                       used, script file operation will be cancelled by
  2090.                       default when an error occurs.
  2091.  
  2092.                       You can use the IF command to test for an error
  2093.                       condition as follows:
  2094.  
  2095.                       > IF ERRORLEVEL != 2
  2096.                       > IF ERRORLEVEL == 6
  2097.  
  2098.  
  2099.  
  2100.  
  2101.                                              - 33 -
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.                       Softerm also provides a special function which
  2109.                       allows you to test for the existence or not of a
  2110.                       filename on disk.  The following examples show how
  2111.                       the EXIST() function can be used with the IF command
  2112.                       to test for filenames:
  2113.  
  2114.                       > IF EXIST("BRUCE.TXT")
  2115.                             or
  2116.                       > FILENAME = "C:\SOFTERM\TEMP\SOFTERM.SS2"
  2117.                       > IF EXIST(FILENAME)
  2118.                             or
  2119.                       > IF !EXIST(FILENAME)
  2120.  
  2121.                       IF commands can be nested.  Each IF command must be
  2122.                       matched to a corresponding ENDIF command for proper
  2123.                       processing.  If ELSE commands are used with nested
  2124.                       IF commands, they will be matched with the first
  2125.                       previous IF command which has not been terminated by
  2126.                       an ENDIF command.
  2127.  
  2128.                       The following is an example of nested IF's:
  2129.  
  2130.                       > IF condition (1)
  2131.                       >    commands processed if condition (1) true
  2132.                       >
  2133.                       >   IF condition (2)
  2134.                       >     commands processed if condition (2) true
  2135.                       >
  2136.                       >   ELSE
  2137.                       >     commands processed if condition (2) false
  2138.                       >
  2139.                       >   ENDIF terminates condition (2)
  2140.                       >
  2141.                       > ELSE
  2142.                       >   commands processed if condition (1) false
  2143.                       >
  2144.                       > ENDIF terminates condition (1)
  2145.  
  2146.                       Operators and variables can be combined to create
  2147.                       expressions which can be evaluated and tested for
  2148.                       True or False in an IF command.  Following are some
  2149.                       examples of the use of expressions in IF commands:
  2150.  
  2151.                       > IF STRINGVAR == 'SMITH'
  2152.                       >
  2153.                       > IF NUMVAR == ((3 * 5) + VALUE1)
  2154.                       >
  2155.                       > IF (GETLENGTH(STRING)) > 7
  2156.  
  2157.                       > IF (REPLY != 'Y'( && (REPLY != 'N')
  2158.                       > GOTO REPLYLOOP
  2159.                       > ENDIF
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.                                              - 34 -
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.                       The script file parameters SV1-SV5 text replacement
  2173.                       variables are substituted before processing of the
  2174.                       IF command.  Care should be taken in substituting a
  2175.                       variable name or a string.  For example:
  2176.  
  2177.                       > STRING = 'C:\SOFTERM\SOFTERM.EXE'
  2178.                       > SV1 = STRING
  2179.                       > IF EXIST(SV1)
  2180.                       > PROMPT (SV1' EXISTS IN THAT DIRECTORY')
  2181.                       > ENDIF
  2182.  
  2183.                       will substitute the value of STRING before
  2184.                       processing the IF EXIST statement.  Including quote
  2185.                       marks around the SV1 would result in a check on the
  2186.                       existence of the file named SV1.  Similarly, you
  2187.                       could use this method:
  2188.  
  2189.                       > SV1 = 'C:\SOFTERM\SOFTERM.EXE'
  2190.                       > IF EXIST(SV1)
  2191.                       > PROMPT (SV1' EXISTS IN THAT DIRECTORY')
  2192.                       > ENDIF
  2193.  
  2194.                       INPUT (arg1,arg2,arg3)
  2195.                       Function: Displays a dialog and allows text input to
  2196.                                 a script
  2197.                       Syntax:
  2198.  
  2199.                            > INPUT (title,prompt,input_var)
  2200.  
  2201.                       where:
  2202.  
  2203.                       TITLE is the text to be displayed in the Input
  2204.                       window's title bar.
  2205.  
  2206.                       PROMPT is the text to be displayed.  The text string
  2207.                       may be up to 32 characters long.
  2208.  
  2209.                       INPUT_VAR is the variable to receive the input,
  2210.                       which can be a maximum of 64 characters.  If
  2211.                       INPUT_VAR is initialized to a value before the INPUT
  2212.                       command is processed, the value will be shown when
  2213.                       the dialog is presented.
  2214.  
  2215.                       The INPUT dialog includes the following information:
  2216.  
  2217.                       o The Script File name
  2218.                       o The text to be displayed
  2219.                       o A text input area
  2220.                       o An OK button
  2221.                       o A Cancel button
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.                                              - 35 -
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.                       Selecting OK accepts the displayed input text and
  2237.                       continues.  Selecting Cancel or Close continues
  2238.                       script processing, but ignores any changes to the
  2239.                       input variable.
  2240.  
  2241.                       As with other functions, INPUT returns a code which
  2242.                       is separate from the input variable.  INPUT returns
  2243.                       0 for OK and a non-zero value for Cancel or Close.
  2244.  
  2245.                       An INPUT command might be included in a script file
  2246.                       to prompt for a filename to be transmitted, or for a
  2247.                       password in a logon sequence.
  2248.  
  2249.                       The following are valid INPUT commands:
  2250.  
  2251.                       > REPLYLOOP:
  2252.                       > SET REPLY = ''
  2253.                       > INPT = INPUT ('Kermit Send','Enter file name to
  2254.                       send',REPLY)
  2255.                       > IF REPLY == ''
  2256.                       > GOTO REPLYLOOP
  2257.                       > ENDIF
  2258.                       > IF INPT != 0
  2259.                       > GOTO CANCEL
  2260.                       > ENDIF
  2261.                       > SET SV1 = REPLY
  2262.                       > SEND (KERMIT,SV1,SV1,,ON)
  2263.                         or
  2264.                       > SET CHOICE = 'Y'
  2265.                       > INPUT (,'Enter more data?',CHOICE)
  2266.                       > IF (CHOICE == '') || (CHOICE == 'Y')
  2267.                       > GOTO MOREDATA
  2268.                       > ENDIF
  2269.  
  2270.                       JUMP label
  2271.                       Function: Transfer command processing to the command
  2272.                                 immediately following a specified Label
  2273.                       Syntax:
  2274.  
  2275.                            > JUMP Label
  2276.  
  2277.                       JUMP functions exactly as the GOTO directive.
  2278.  
  2279.                       LOG (arg1)
  2280.                       Function: Create a log file of all commands run by a
  2281.                                 script file
  2282.                       Syntax:
  2283.  
  2284.                            > LOG (d:\path\filename.ext)
  2285.  
  2286.                       If the specified log file already exists, it is de-
  2287.                       leted and a new file is opened.  Wildcard characters
  2288.                       are not allowed in the log file name entered.  The
  2289.  
  2290.  
  2291.  
  2292.  
  2293.                                              - 36 -
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.                       log file is created and written in standard text
  2301.                       file format.
  2302.  
  2303.                       An initial entry is written to the log file when the
  2304.                       command begins and a copy of the current command
  2305.                       line with including arguments and switches is
  2306.                       written to the log file.  The final Characters,
  2307.                       Blocks, and Errors counts displayed during SEND(),
  2308.                       RECEIVE(), and HOST() commands also are written to
  2309.                       the log file.
  2310.  
  2311.                       Once initiated by the LOG command, logging remains
  2312.                       active until a NOLOG, END or CONVERSE command is
  2313.                       performed, or the current script file is cancelled.
  2314.  
  2315.                       Once the log file is opened, any subsequent commands
  2316.                       will be recorded.  Each command recorded in the log
  2317.                       file will include the current date and time in
  2318.                       MM/DD/YY  HH:MM:SS format.  An I/O error while
  2319.                       writing to the log file will cause it to be closed.
  2320.                       The log file created may be printed or viewed.
  2321.  
  2322.                       Note:  Multiple LOG files cannot be open at the same
  2323.                       time.  If a LOG command is performed while a log
  2324.                       file already is open, the first log file will be
  2325.                       closed and the new log file opened.  If the command
  2326.                       specifies the same file name as the previous log
  2327.                       file, the previous log file is replaced.
  2328.  
  2329.                       LOWER (arg1)
  2330.                       Function: Returns a lower case text string
  2331.                       Syntax:
  2332.  
  2333.                            > LOWER (source_string)
  2334.  
  2335.                       where:
  2336.  
  2337.                       SOURCE_STRING is the source text string (maximum
  2338.                       length 255 characters).
  2339.  
  2340.                       Example:
  2341.  
  2342.                       > LOWCASE = LOWER ('THIS IS A TEST")
  2343.                             or
  2344.                       > TXT = 'THIS IS A TEST'
  2345.                       > LOWCASE = LOWER (TXT)
  2346.  
  2347.                       The variable LOWCASE will contain the string 'this
  2348.                       is a test'.
  2349.  
  2350.  
  2351.  
  2352.  
  2353.  
  2354.  
  2355.  
  2356.  
  2357.                                              - 37 -
  2358.  
  2359.  
  2360.  
  2361.  
  2362.  
  2363.  
  2364.                       MESSAGE (arg1)
  2365.                       Function: Displays a message in the progress frame
  2366.                                 window
  2367.                       Syntax:
  2368.  
  2369.                            > MESSAGE (text)
  2370.  
  2371.                       where:
  2372.  
  2373.                       TEXT is the information text to be displayed.  The
  2374.                       string can contain a maximum of 255 characters.  The
  2375.                       text will remain until it scrolls off the progress
  2376.                       frame window.
  2377.  
  2378.                       Note:  If the script progress frame window is
  2379.                       covered by another window, the text string will not
  2380.                       be visible.
  2381.  
  2382.                       MKDIR (arg1)
  2383.                       Function: Create a directory path
  2384.                       Syntax:
  2385.  
  2386.                             > MKDIR (path_name)
  2387.  
  2388.                       where:
  2389.  
  2390.                       PATH_NAME is the directory path text string.
  2391.  
  2392.                       NEXTFILE (arg1)
  2393.                       Function: Returns an information text string for the
  2394.                                 next file matching the file name template
  2395.                                 specified in a FIRSTFILE function
  2396.                       Syntax:
  2397.  
  2398.                       > NEXTFILE (filedef)
  2399.  
  2400.                       where:
  2401.  
  2402.                       FILEDEF is the name of a variable that contains the
  2403.                       unique identifier value that was returned by the
  2404.                       previous FIRSTFILE function.
  2405.  
  2406.                       The returned information text string will be a null
  2407.                       if there are no files matching the specified
  2408.                       template;  else the string will take the format
  2409.                       defined for the FIRSTFILE function.
  2410.  
  2411.                       NOLOG ()
  2412.                       Function: Cancel the logging started by the LOG()
  2413.                                 function
  2414.                       Syntax:
  2415.  
  2416.                            > NOLOG()
  2417.  
  2418.  
  2419.  
  2420.  
  2421.                                              - 38 -
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.                       ON (arg1,arg2,......,arg11)
  2429.                       Function: Provides conditional branching to a label
  2430.                                 within a script file based upon a numeric
  2431.                                 value
  2432.                       Syntax:
  2433.  
  2434.                            > ON (numeric_val,label_1,label_2,...,label_10)
  2435.  
  2436.                       where:
  2437.  
  2438.                       NUMERIC_VAL is a numeric value in the range 1 to 10
  2439.                       typically obtained from a preceding XMIT_WAIT()
  2440.                       function.  If the value is less than 1 or greater
  2441.                       than 10, or if no Label is defined for the value,
  2442.                       processing will continue immediately with the first
  2443.                       statement following the ON command.
  2444.  
  2445.  
  2446.                       LABEL_1 to LABEL_10 are the label names that
  2447.                       correspond to the numeric values 1 to 10.
  2448.  
  2449.                       Important:  The value for 'arg1' often will be
  2450.                       provided by using a preceding XMIT_WAIT() function.
  2451.                       For example:
  2452.  
  2453.                       > ARG1_VAL = XMIT_WAIT (xmit_str,arg2,...,arg11)
  2454.                       > ON (ARG1_VAL,label_1,label_2,...,label_10)
  2455.  
  2456.                       ONERR label
  2457.                       Function: When a serious error -- one which would
  2458.                                 cause Script file processing to terminate
  2459.                                 -- occurs, transfer command processing to
  2460.                                 the specified Label
  2461.                       Syntax:
  2462.  
  2463.                            > ONERR Label
  2464.  
  2465.                       Note:  Related directives and a reserved variable
  2466.                       are:  IF, ERRORLEVEL, RESUME and RETRY.
  2467.  
  2468.                       If an ONERR directive is used in a script file, when
  2469.                       a serious error condition occurs processing will
  2470.                       continue with the first command following a LABEL
  2471.                       whose name matches the ONERR command label.  If no
  2472.                       LABEL is found with a matching name, command
  2473.                       processing is cancelled.
  2474.  
  2475.                       If the ONERR directive is not used in a script file,
  2476.                       processing of the file is cancelled when a serious
  2477.                       error condition occurs.
  2478.  
  2479.                       Caution: When using the ONERR directive, it is
  2480.                       possible to create looping conditions.  For example,
  2481.                       running a script file using Softrans protocol to
  2482.  
  2483.  
  2484.  
  2485.                                              - 39 -
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.                       RECEIVE a file which does not exist when the ONERR
  2493.                       processing is set to RETRY the RECEIVE operation
  2494.                       will cause looping.
  2495.  
  2496.                       Error conditions recognized by this directive
  2497.                       include:  expression evaluation errors;  line
  2498.                       timeout errors when using the character protocol;
  2499.                       line failure errors which occur when the RETRIES
  2500.                       count expires;  operator cancel errors;  remote
  2501.                       cancel errors when using the Softrans and Kermit
  2502.                       protocols;  disk errors;  and line disconnects due
  2503.                       to loss of carrier.
  2504.  
  2505.                       Note:  An operator cancel or a line timeout which
  2506.                       terminates a character mode RECEIVE operation is not
  2507.                       considered to be a serious error.
  2508.  
  2509.                       OPENNEW (arg1,arg2)
  2510.                       Function: Creates and opens a new file
  2511.                       Syntax:
  2512.  
  2513.                            > OPENNEW(filename.new,filedef)
  2514.  
  2515.                       where:
  2516.  
  2517.                       FILENAME.NEW is the file name text string.
  2518.  
  2519.                       FILEDEF must be the name of a variable to receive
  2520.                       the file open handle that will be used as an
  2521.                       argument in subsequent functions that access the
  2522.                       same file.
  2523.  
  2524.                       Examples:
  2525.  
  2526.                       > RESULT = OPENNEW('PAYROLL.DOC',FILDEF)
  2527.                             or
  2528.                       > FILENAME = 'PAYROLL.DOC'
  2529.                       > RESULT = OPENNEW(FILENAME,FILDEF)
  2530.  
  2531.                       On completion of the command, a result code is
  2532.                       returned to the variable RESULT.  A result code of 0
  2533.                       (zero) means the command was successful;  a non-zero
  2534.                       value indicates that the command was not successful.
  2535.  
  2536.                       OPENOLD (arg1,arg2)
  2537.                       Function: Opens an existing file
  2538.                       Syntax:
  2539.  
  2540.                            > OPENOLD(filename.old,filedef)
  2541.  
  2542.                       where:
  2543.  
  2544.                       FILENAME.OLD is the file name text string.
  2545.  
  2546.  
  2547.  
  2548.  
  2549.                                              - 40 -
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.                       FILEDEF must be the name of a variable to receive
  2557.                       the file open handle that will be used as an
  2558.                       argument in subsequent functions that access the
  2559.                       same file.
  2560.  
  2561.                       Examples:
  2562.  
  2563.                       > RESULT = OPENOLD('GRADES.CL3',FILDEF)
  2564.                             or
  2565.                       > FILENAME = 'GRADES.CL3'
  2566.                       > RESULT = OPENOLD(FILENAME,FILDEF)
  2567.  
  2568.                       On completion of the command, a result code is
  2569.                       returned to the variable RESULT.  A result code of 0
  2570.                       (zero) means the command was successful;  a non-zero
  2571.                       value indicates that the command was not successful.
  2572.  
  2573.                       Note:  On an OPENOLD command, the internal file
  2574.                       pointer will be set at the start of the file.
  2575.  
  2576.                       PAUSE (arg1)
  2577.                       Function: Delay the start of the next script file
  2578.                                 command
  2579.                       Syntax:
  2580.  
  2581.                            > PAUSE (seconds)
  2582.  
  2583.                       The desired pause time in seconds is entered as the
  2584.                       argument.  A value from 1 to 255 seconds may be
  2585.                       specified for the pause.  The delay indicated is
  2586.                       processed immediately and no further script commands
  2587.                       are processed until the pause interval is complete.
  2588.  
  2589.                       This function may be necessary when transferring
  2590.                       files with some host computer systems to allow
  2591.                       preparation time before the next command is
  2592.                       processed.
  2593.  
  2594.                       PROMPT (arg1,arg2)
  2595.                       Function: Displays an information message dialog box
  2596.                                 until dismissed by the operator
  2597.                       Syntax:
  2598.  
  2599.                            > PROMPT (title,text)
  2600.  
  2601.                       where:
  2602.  
  2603.                       TITLE is the text which will be displayed in the
  2604.                       prompt's title bar.
  2605.  
  2606.                       TEXT is the information text to be displayed.  The
  2607.                       string can contain a maximum of 255 characters.
  2608.  
  2609.  
  2610.  
  2611.  
  2612.  
  2613.                                              - 41 -
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.                       Note:  If the window in which the Script file is
  2621.                       running is not the current window, the text string
  2622.                       will not be visible and no action can be taken.
  2623.  
  2624.                       READ (arg1,arg2)
  2625.                       Function: Returns a text string from an open file
  2626.                       Syntax:
  2627.  
  2628.                            > READ (filedef,numeric_val)
  2629.  
  2630.                       where:
  2631.  
  2632.                       FILEDEF must be the name of a variable that contains
  2633.                       the handle returned by a previous file open
  2634.                       function.
  2635.  
  2636.                       NUMERIC_VAL is the numeric value of the length of
  2637.                       data to be read.
  2638.  
  2639.                       Examples:
  2640.  
  2641.                       > TXT = READ (FILEDEF,20)
  2642.                             or
  2643.                       > READCOUNT = 20
  2644.                       > TXT = READ (FILDEF,READCOUNT)
  2645.  
  2646.                       TXT is a variable to receive the data read, and
  2647.                       READCOUNT is a numeric variable or constant
  2648.                       indicating the amount of data to be read (255
  2649.                       characters maximum). The returned TXT string will be
  2650.                       a null length string if the current file position is
  2651.                       at the End-of-File.  If less data is available than
  2652.                       READCOUNT, the read still will be performed without
  2653.                       error and the amount of data read may be determined
  2654.                       using the GETLENGTH function.
  2655.  
  2656.                       READLINE (arg1)
  2657.                       Function: Returns a line of text from an open file
  2658.                       Syntax:
  2659.  
  2660.                            > READLINE (filedef)
  2661.  
  2662.                       where:
  2663.  
  2664.                       FILEDEF must be the name of a variable that contains
  2665.                       the handle returned by a previous file open
  2666.                       function.
  2667.  
  2668.                       Example:
  2669.  
  2670.                       > TXT = READLINE (FILEDEF)
  2671.  
  2672.                       TXT is a variable to receive the data read.  A line
  2673.                       of data is a maximum of 255 characters terminated by
  2674.  
  2675.  
  2676.  
  2677.                                              - 42 -
  2678.  
  2679.  
  2680.  
  2681.  
  2682.  
  2683.  
  2684.                       CR, LF, CR+LF or LF+CR.  The terminator sequence is
  2685.                       not returned with the read data.  The returned TXT
  2686.                       will have a length of 1 and will contain a control-Z
  2687.                       (26 decimal) character if the internal file pointer
  2688.                       is at End-of-File.
  2689.  
  2690.                       You can copy, profile and run the following script
  2691.                       to demonstrate the READLINE() function:
  2692.  
  2693.                       > windowpos (0,0)
  2694.                       > windowtitle ('ReadLine Test - ' + sessionname)
  2695.                       > windowsize (24,80)
  2696.                       > windowprms (off,200,201)
  2697.                       > watch (off,on,3)
  2698.                       > windowshow ()
  2699.                       > delete ('\openold.000')
  2700.                       > copy ('\config.sys','\openold.000',replace)
  2701.                       > openold ('\openold.000',handle)
  2702.                       > read:
  2703.                       > text = readline (handle)
  2704.                       > if ((getlength (text) == 1) && (chrtoval (text) == 26))
  2705.                       >   message ('Press any key to terminate script')
  2706.                       >   timeout = 0
  2707.                       >   watch (on)
  2708.                       >   wait ()
  2709.                       >   close (handle)
  2710.                       >   delete ('\openold.000')
  2711.                       >   end
  2712.                       > endif
  2713.                       > message (text)
  2714.                       > goto read
  2715.  
  2716.                       RECEIVE (arg1,arg2,arg3,arg4,arg5,arg6,arg7)
  2717.                       Function: Transfer a file from a host to your PC
  2718.                       Syntax:
  2719.  
  2720.                            > RECEIVE    (protocol,host_filename,
  2721.                                 local_filename,if_exist,xmit,
  2722.                                 display_stats,display_filename)
  2723.  
  2724.                       where:
  2725.  
  2726.                       PROTOCOL is a text string defining either a file
  2727.                       transfer protocol profile or a file transfer
  2728.                       protocol name.  If a profile has the same name as a
  2729.                       protocol, this argument will use the profile.
  2730.  
  2731.                       HOST_FILENAME is the file name as it appears on the
  2732.                       host system.
  2733.  
  2734.                       LOCAL_FILENAME is the name to be assigned to the
  2735.                       file on the local PC.
  2736.  
  2737.  
  2738.  
  2739.  
  2740.  
  2741.                                              - 43 -
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.                       IF_EXIST is the option to use if a file with the
  2749.                       LOCAL_FILENAME already exists.  The options are:
  2750.  
  2751.                       Replace   Overwrite the existing file with the new
  2752.                                 file.
  2753.                       Append    Add the contents of the new file to the
  2754.                                 end of the existing file.  This generally
  2755.                                 is not a appropriate option to use with
  2756.                                 binary files.
  2757.                       Fail      Cancel the Receive operation.  This is the
  2758.                                 default.
  2759.  
  2760.                       XMIT is the initial transmit text string.
  2761.  
  2762.                       DISPLAY_STATS specifies whether the file transfer
  2763.                       statistics should or should not be displayed.  Note:
  2764.                       The statistics display is described in the Session
  2765.                       Window: File Menu chapter.  The allowable values are:
  2766.  
  2767.                       ON      Display statistics
  2768.                       OFF     Do not display statistics
  2769.  
  2770.                       DISPLAY_FILENAME specifies whether the names of the
  2771.                       files being transferred should or should not be
  2772.                       displayed in the Script window.  The allowable
  2773.                       values are:
  2774.  
  2775.                       ON      Display names (the default)
  2776.                       OFF     Do not display names
  2777.  
  2778.                       Examples:
  2779.  
  2780.                       > RECEIVE ('character','letter.txt',
  2781.                                 'letter.txt',append,
  2782.                                 'type letter.txt[CR]',on,off)
  2783.  
  2784.                             or
  2785.  
  2786.                       > SV1 = 'kermit'
  2787.                       > SV2 = 'project.dbf'
  2788.                       > SV3 = 'kermit -s '+SV2+'[CR]'
  2789.                       > RECEIVE (SV1,,SV2,replace,SV3,off,on)
  2790.  
  2791.                       RENAME (arg1,arg2)
  2792.                       Function: Renames a file
  2793.                       Syntax:
  2794.  
  2795.                            > RENAME (old_name,new_name)
  2796.  
  2797.                       where:
  2798.  
  2799.                         OLD_NAME is the current file name text string.
  2800.  
  2801.                         NEW_NAME is the new file name text string.
  2802.  
  2803.  
  2804.  
  2805.                                              - 44 -
  2806.  
  2807.  
  2808.  
  2809.  
  2810.  
  2811.  
  2812.                       Example:
  2813.  
  2814.                       > RENAME ('SETHRPT.TXT','SETHRPT.BK1')
  2815.  
  2816.                       RESUME
  2817.                       Function: Used in ONERR directive processing to
  2818.                                 resume processing with the next command
  2819.                                 after the command on which an error
  2820.                                 occurred
  2821.                       Syntax:
  2822.  
  2823.                            > RESUME
  2824.  
  2825.                       This directive requires no additional parameters.
  2826.                       If it is processing as a result of ONERR processing,
  2827.                       the next command after the command on which the
  2828.                       error occurred will be processing.
  2829.  
  2830.                       This directive is ignored when an error has not
  2831.                       occurred.
  2832.  
  2833.                       RETRY
  2834.                       Function: Used with ONERR directive processing to
  2835.                                 retry the command on which an error
  2836.                                 occurred
  2837.                       Syntax:
  2838.  
  2839.                            > RETRY
  2840.  
  2841.                       If this command is processed as a result of ONERR
  2842.                       processing after an error has occurred, the command
  2843.                       on which the error occurred will be re-processed.
  2844.  
  2845.                       Example:
  2846.  
  2847.                       > ONERR Error
  2848.                       > DIAL ()
  2849.                       .
  2850.                       > Error:
  2851.                       > IF ERRORLEVEL == 1
  2852.                       > RETRY
  2853.                       > ELSE
  2854.                       > GOTO EXIT
  2855.                       > ENDIF
  2856.  
  2857.                       Important:  Incorrect use of the RETRY directive can
  2858.                       cause looping.
  2859.  
  2860.                       This directive is ignored when an error has not
  2861.                       occurred.
  2862.  
  2863.  
  2864.  
  2865.  
  2866.  
  2867.  
  2868.  
  2869.                                              - 45 -
  2870.  
  2871.  
  2872.  
  2873.  
  2874.  
  2875.  
  2876.                       RSTATTR (arg1,arg2)
  2877.                       Function: Resets a file attribute
  2878.                       Syntax:
  2879.  
  2880.                             > RSTATTR (fname,attrib)
  2881.  
  2882.                       where:
  2883.  
  2884.                       FNAME is the file name text string.
  2885.  
  2886.                       ATTRIB is a text list which can contain any
  2887.                       combination of the A, H, and R attribute characters,
  2888.                       as described in the FINDFIRST function.  The volume,
  2889.                       sub-directory, and system attributes may not be
  2890.                       reset.
  2891.  
  2892.                       Examples:
  2893.  
  2894.                       > RSTATTR('C:\SOFTERM\SOFT.PWD','AH')
  2895.                             or
  2896.                       > FILENAME = 'C:\SOFTERM\SOFT.PWD'
  2897.                       > RSTATTR(FILENAME,'H')
  2898.                             or
  2899.                       > RESULT = RSTATTR(FILENAME,'AHR')
  2900.  
  2901.                       On completion of the last example, a result code is
  2902.                       returned to the variable RESULT.  A result code of 0
  2903.                       (zero) means the command was successful;  a non-zero
  2904.                       value indicates that the command was not successful.
  2905.  
  2906.                       SEND (arg1,arg2,arg3,arg4,arg5,arg6)
  2907.                       Function: Transfer a file from your PC to a host
  2908.                       Syntax:
  2909.  
  2910.                            > SEND (protocol,local_filename,host_filename,
  2911.                              xmit,display_stats,display_filename)
  2912.  
  2913.                       where:
  2914.  
  2915.                       PROTOCOL is a text string defining either a file
  2916.                       transfer protocol profile or a file transfer
  2917.                       protocol name.  If a profile has the same name as a
  2918.                       protocol, this argument will use the protocol.
  2919.  
  2920.                       LOCAL_FILENAME is the name as it appears on the
  2921.                       local PC.
  2922.  
  2923.                       HOST_FILENAME is the name to be assigned to the file
  2924.                       on the host system.
  2925.  
  2926.                       XMIT is the initial transmit text string.
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.                                              - 46 -
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.                       DISPLAY_STATS specifies whether the file transfer
  2941.                       statistics should or should not be displayed.  Note:
  2942.                       The statistics display is described in the Session
  2943.                       Window: File Menu chapter.  The allowable values
  2944.                       are:
  2945.  
  2946.                       ON      Display statistics
  2947.                       OFF     Do not display statistics
  2948.  
  2949.                       DISPLAY_FILENAME specifies whether the names of the
  2950.                       files being transferred should or should not be
  2951.                       displayed in the Script window.  The allowable
  2952.                       values are:
  2953.  
  2954.                       ON      Display names (the default)
  2955.                       OFF     Do not display names
  2956.  
  2957.                       Examples:
  2958.  
  2959.                       > SEND ('character','letter.txt','letter.txt',
  2960.                              'accept letter.txt[CR]',on,off)
  2961.                             or
  2962.                       > SV1 = 'kermit'
  2963.                       > SV2 = 'project.dbf'
  2964.                       > SV3 = 'kermit -r '+SV2+'[CR]'
  2965.                       > SEND (SV1,,SV2,SV3,off,on)
  2966.  
  2967.                       SETATTR (arg1,arg2)
  2968.                       Function: Sets a file attribute
  2969.                       Syntax:
  2970.  
  2971.                            > SETATTR (fname,attrib)
  2972.  
  2973.                       where:
  2974.  
  2975.                       FNAME is the file name text string.
  2976.  
  2977.                       ATTRIB is a text list which can contain any
  2978.                       combination of the A, H, and R attribute characters,
  2979.                       as described in the FINDFIRST function.  Refer to
  2980.                       the RSTATTR function for additional information.
  2981.  
  2982.                       SETBOF (arg1)
  2983.                       Function: Sets the current file position to
  2984.                                 beginning-of-file
  2985.                       Syntax:
  2986.  
  2987.                            > SETBOF (filedef)
  2988.  
  2989.                       where:
  2990.  
  2991.                       FILEDEF must be the name of a variable that contains
  2992.                       the handle returned by a previous file open
  2993.                       function.
  2994.  
  2995.  
  2996.  
  2997.                                              - 47 -
  2998.  
  2999.  
  3000.  
  3001.  
  3002.  
  3003.  
  3004.                       SETEOF (arg1)
  3005.                       Function: Sets the current file position to end-
  3006.                                 of-file
  3007.                       Syntax:
  3008.  
  3009.                            > SETEOF (filedef)
  3010.  
  3011.                       where:
  3012.  
  3013.                       FILEDEF must be the name of a variable that contains
  3014.                       the handle returned by a previous file open
  3015.                       function.
  3016.  
  3017.                       SKIP (arg1,arg2)
  3018.                       Function: Sets the file position relative to the
  3019.                                 current file position
  3020.                       Syntax:
  3021.  
  3022.                            > SKIP (filedef,skipcount)
  3023.  
  3024.                       where:
  3025.  
  3026.                       FILEDEF must be the name of a variable that contains
  3027.                       the handle returned by a previous file open
  3028.                       function.
  3029.  
  3030.                       SKIPCOUNT is the numeric reposition value.
  3031.  
  3032.                       This function will adjust the current position of
  3033.                       the pointer in the file referenced by the file
  3034.                       definition variable FILDEF by the number of
  3035.                       characters defined by the argument SKIPCOUNT.
  3036.                       SKIPCOUNT is a numeric string indicating forward or
  3037.                       backward position adjustment in the range
  3038.                       -2,147,483,648 to +2,147,483,647 or a numeric
  3039.                       variable defining the reposition count.  Omission of
  3040.                       the leading sign in the case of a numeric string
  3041.                       implies a forward reposition.
  3042.  
  3043.                       > SKIP (FILDEF,-10)
  3044.                             or
  3045.                       > SKIPCOUNT = -10
  3046.                       > RESULT = SKIP (FILDEF,SKIPCOUNT)
  3047.  
  3048.                       On completion of the command, a result code is
  3049.                       returned to the variable RESULT.  A result code of 0
  3050.                       (zero) means the command was successful;  a non-zero
  3051.                       value indicates that the command was not successful.
  3052.  
  3053.  
  3054.  
  3055.  
  3056.  
  3057.  
  3058.  
  3059.  
  3060.  
  3061.                                              - 48 -
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.                       STRFIND1 (arg1,arg2,arg3)
  3069.                       Function: Returns the numeric position of the start
  3070.                                 of a specified text string within a text
  3071.                                 string.  A value of zero is returned if
  3072.                                 the specified string is not found.
  3073.                       Syntax:
  3074.  
  3075.                            > STRFIND1 (var_name,text,which)
  3076.  
  3077.                       where:
  3078.  
  3079.                       VAR_NAME is the name of the variable to be searched
  3080.                       and may be defined as the read-only predefined
  3081.                       system variable, RXDATA, which contains the last 255
  3082.                       characters received by the most recent XMIT_WAIT
  3083.                       function.
  3084.  
  3085.                       TEXT is the text string to find (maximum length 255
  3086.                       characters).
  3087.  
  3088.                       WHICH is the occurrence to be found.  A value of
  3089.                       zero will locate the final occurrence.
  3090.  
  3091.                       Important:  STRFIND1() is not case sensitive;  lower
  3092.                       case will match upper case when performing the
  3093.                       search.
  3094.  
  3095.                       Examples:
  3096.  
  3097.                       > SRCH = 'FT'
  3098.                       > POS = STRFIND1(SRCH,'Softerm does the job!',1)
  3099.  
  3100.                       The numeric variable POS will contain 3, which is
  3101.                       the value of the position of the first occurence of
  3102.                       the specified text string in the text string defined
  3103.                       by the text variable SRCH.
  3104.  
  3105.                       > TXT = 'Four score and seven years ago,...'
  3106.                       > POS = STRFIND1 (RXDATA,TXT,0)
  3107.  
  3108.                       This is similar to the first example, except a text
  3109.                       variable is used to hold the search string and the
  3110.                       last 255 characters received by the most recent
  3111.                       XMIT_WAIT function are searched for the last
  3112.                       occurence of the search text.
  3113.  
  3114.  
  3115.  
  3116.  
  3117.  
  3118.  
  3119.  
  3120.  
  3121.  
  3122.  
  3123.  
  3124.  
  3125.                                              - 49 -
  3126.  
  3127.  
  3128.  
  3129.  
  3130.  
  3131.  
  3132.                       STRFIND2 (arg1,arg2,arg3)
  3133.                       Function: Returns the numeric position of any
  3134.                                 character from a specified text list
  3135.                                 within a text string.  A value of zero is
  3136.                                 returned if no characters from the
  3137.                                 specified list are found in the specified
  3138.                                 string.
  3139.                       Syntax:
  3140.  
  3141.                            > STRFIND2 (var_name,list,which)
  3142.  
  3143.                       where:
  3144.  
  3145.                       VAR_NAME is the name of the variable which contains
  3146.                       the source string.  This may be defined as the read-
  3147.                       only predefined system variable, RXDATA, which
  3148.                       contains the last 255 characters received by the
  3149.                       most recent XMIT_WAIT function.
  3150.  
  3151.                       LIST is the text string that is the list of
  3152.                       characters (maximum length 255 characters).
  3153.  
  3154.                       WHICH is the occurrence to be found.  A value of
  3155.                       zero will locate the final occurrence.
  3156.  
  3157.                       Important:  STRFIND2() is not case sensitive;  lower
  3158.                       case will match upper case when performing the
  3159.                       search.
  3160.  
  3161.                       Examples:
  3162.  
  3163.                       > POS = STRFIND2 (RXDATA,VALTOCHR(30),0)
  3164.  
  3165.                       The numerical variable POS will contain the position
  3166.                       of the last occurence of the Record Separator
  3167.                       character in the RXDATA string.  If POS is zero, no
  3168.                       Record Separator character was located in the
  3169.                       string.
  3170.  
  3171.                       > POS = STRFIND2 (TXT_VAR,'XYZ',1)
  3172.  
  3173.                       The numerical variable POS will contain the position
  3174.                       of the first occurence of 'x', 'X', 'y', 'Y', 'z' or
  3175.                       'Z' in the TXT_VAR string.  If POS is zero, none of
  3176.                       the specified characters was located in the string.
  3177.  
  3178.                       > POS = STRFIND2 (TXT_VAR,'\',0)
  3179.  
  3180.                       The numerical variable POS will contain the position
  3181.                       of the last occurence of the path separator '\' in
  3182.                       the TXT_VAR string.  If POS is zero, the character
  3183.                       was not located in the string.
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.                                              - 50 -
  3190.  
  3191.  
  3192.  
  3193.  
  3194.  
  3195.  
  3196.                       STRGET1 (arg1,arg,arg3)
  3197.                       Function: Extracts a text string from a text string
  3198.                                 by length
  3199.                       Syntax:
  3200.  
  3201.                            > STRGET1 (var_name,start_pos,length)
  3202.  
  3203.                       where:
  3204.  
  3205.                       VAR_NAME is the name of the variable which contains
  3206.                       the source string.  This may be defined as the read-
  3207.                       only predefined system variable, RXDATA, which
  3208.                       contains the last 255 characters received by the
  3209.                       most recent XMIT_WAIT function.
  3210.  
  3211.                       START_POS is the numeric value of the extraction
  3212.                       start position.  This value generally is obtained
  3213.                       from one of the STRFIND functions.
  3214.  
  3215.                       LENGTH is the numeric value of the length of the
  3216.                       string to be extracted (maximum length 255
  3217.                       characters).
  3218.  
  3219.                       Example:
  3220.  
  3221.                       > POS = STRFIND1(SRCH,'soft',1)
  3222.                       > TXT = STRGET1 (SRCH,POS,21)
  3223.  
  3224.                       Using the results of the STRFIND1() example, the
  3225.                       STRGET1() command would return the text variable TXT
  3226.                       with 'Softerm does the job!'
  3227.  
  3228.                       STRGET2 (arg1,arg,arg3)
  3229.                       Function: Extracts a text string from a text string
  3230.                                 terminated by a specific terminator
  3231.                                 character from a text string
  3232.                       Syntax:
  3233.  
  3234.                            > STRGET2 (var_name,start_pos,termchar_list)
  3235.  
  3236.                       where:
  3237.  
  3238.                       VAR_NAME is the name of the variable which contains
  3239.                       the source string.  This may be defined as the read-
  3240.                       only predefined system variable, RXDATA, which
  3241.                       contains the last 255 characters received by the
  3242.                       most recent XMIT_WAIT function.
  3243.  
  3244.                       START_POS is the numeric value of the extraction
  3245.                       start position.  This value generally is obtained
  3246.                       from one of the STRFIND functions.
  3247.  
  3248.                       TERMCHAR_LIST is the termination character list.
  3249.  
  3250.  
  3251.  
  3252.  
  3253.                                              - 51 -
  3254.  
  3255.  
  3256.  
  3257.  
  3258.  
  3259.  
  3260.                       Example:
  3261.  
  3262.                       > POS = STRFIND1(SRCH,'soft',1)
  3263.                       > TXT = STRGET2 (SRCH,POS,'!')
  3264.  
  3265.                       Using the results of the STRFIND1() example, the
  3266.                       STRGET1() command would return the text variable TXT
  3267.                       with 'Softerm does the job!'
  3268.  
  3269.                       STRPUT (arg1,arg2,arg3)
  3270.                       Function: Puts a text substring within a text
  3271.                                 string, replacing any existing characters
  3272.                       Syntax:
  3273.  
  3274.                            > STRPUT (source,text,start_pos)
  3275.  
  3276.                       where:
  3277.  
  3278.                       SOURCE is the source text string (maximum length 255
  3279.                       characters).
  3280.  
  3281.                       TEXT is the replacement text string (maximum length
  3282.                       255 characters).
  3283.  
  3284.                       START_POS is the numeric value of the start
  3285.                       position.  This value generally is obtained from one
  3286.                       of the STRFIND functions.
  3287.  
  3288.                       STRTOVAL (arg1)
  3289.                       Function: Returns the numeric value representing an
  3290.                                 ASCII numeric text string (for example,
  3291.                                 '123' is returned as 123)
  3292.                       Syntax:
  3293.  
  3294.                             > STRTOVAL ('numeric_string')
  3295.  
  3296.                       where:
  3297.  
  3298.                       'NUMERIC_STRING' is the ASCII numeric text string.
  3299.  
  3300.                       Example:
  3301.  
  3302.                       > NUM_VAL = STRTOVAL ('754')
  3303.  
  3304.                       The numeric variable NUM_VAL will contain the
  3305.                       decimal number 754 (seven hundred fifty-four).
  3306.  
  3307.                       STRTOVAL() is used to convert ASCII text to a binary
  3308.                       value.  It typically is used to convert operator
  3309.                       input to a numeric variable that can be used for
  3310.                       arithmetic operations.  For example, the following
  3311.                       commands implement a simple command loop:
  3312.  
  3313.  
  3314.  
  3315.  
  3316.  
  3317.                                              - 52 -
  3318.  
  3319.  
  3320.  
  3321.  
  3322.  
  3323.  
  3324.                       > ;operator input is placed in the
  3325.                       > ; text variable TEXTCOUNT
  3326.                       > COUNT = STRTOVAL(TEXTCOUNT)
  3327.                       > LOOP:
  3328.                       > IF !COUNT
  3329.                       > GOTO LOOPEND
  3330.                       > ELSE
  3331.                       > COUNT = COUNT - 1
  3332.                       > GOTO LOOP
  3333.                       > LOOPEND:
  3334.  
  3335.                       Before operator input can be used in an arithmetic
  3336.                       operation, it must be converted to a numeric varia-
  3337.                       ble.  STRTOVAL() performs this function.
  3338.  
  3339.                       UPPER (arg1)
  3340.                       Function: Returns an upper case text string
  3341.                       Syntax:
  3342.  
  3343.                            > UPPER (source_string)
  3344.  
  3345.                       where:
  3346.  
  3347.                       SOURCE_STRING is the source text string (maximum
  3348.                       length 255 characters).
  3349.  
  3350.                       Example:
  3351.  
  3352.                       > UPCASE = UPPER ('this is a test")
  3353.                             or
  3354.                       > TXT = 'this is a test'
  3355.                       > UPCASE = UPPER (TXT)
  3356.  
  3357.                       The variable UPCASE will contain the string 'THIS IS
  3358.                       A TEST'.
  3359.  
  3360.                       VALTOCHR (arg1)
  3361.                       Function: Returns the ASCII character representing a
  3362.                                 numeric value (for example, 49 is returned
  3363.                                 as '1')
  3364.                       Syntax:
  3365.  
  3366.                            > VALTOCHR (numeric)
  3367.  
  3368.                       where:
  3369.  
  3370.                       NUMERIC is a numeric value in the range 0 through
  3371.                       255.
  3372.  
  3373.  
  3374.  
  3375.  
  3376.  
  3377.  
  3378.  
  3379.  
  3380.  
  3381.                                              - 53 -
  3382.  
  3383.  
  3384.  
  3385.  
  3386.  
  3387.  
  3388.                       Example:
  3389.  
  3390.                       > ASC_CHAR = VALTOCHR (65)
  3391.  
  3392.                       The ASCII text variable ASC_CHAR will contain the
  3393.                       ASCII character 'A'.
  3394.  
  3395.                       VALTOSTR (arg1)
  3396.                       Function: Returns the ASCII numeric text string
  3397.                                 representing a numeric value
  3398.                       Syntax:
  3399.  
  3400.                            > VALTOSTR (numeric_val)
  3401.  
  3402.                       where:
  3403.  
  3404.                       NUMERIC_VAL is the numeric value.
  3405.  
  3406.                       Example:
  3407.  
  3408.                       > ASC_VAL = VALTOSTR (754)
  3409.  
  3410.                       The text variable ASC_VAL will contain the ASCII
  3411.                       string '754'.
  3412.  
  3413.                       VALTOSTR() is the inverse of STRTOVAL();  it
  3414.                       converts a numeric value to a string value.  For
  3415.                       example, to report the counting process, the above
  3416.                       command sequence could be modified as follows:
  3417.  
  3418.                       > ;operator input is placed in the
  3419.                       > ; text variable TEXTCOUNT
  3420.                       > COUNT = STRTOVAL(TEXTCOUNT)
  3421.  
  3422.                       > LOOP:
  3423.                       > IF !COUNT
  3424.                       > GOTO LOOPEND
  3425.                       > ENDIF
  3426.                       > SV1 = VALTOSTR(COUNT)
  3427.                       > MESSAGE ('Current count is 'SV1)
  3428.                       > COUNT = COUNT - 1
  3429.                       > GOTO LOOP
  3430.  
  3431.                       If you set a variable equal to a numeric value,
  3432.                       remember that Softerm stores numeric values in
  3433.                       binary format, not text.  Therefore, you would need
  3434.                       to use the function VALTOSTR() (Value-To-String) to
  3435.                       use the variable as an ASCII character.
  3436.  
  3437.                       The reserved variable, ERRORCODE, contains the
  3438.                       numeric value of the last error code generated.  For
  3439.                       instance, if you had an error trap routine that
  3440.                       displayed the error value, you would need to convert
  3441.                       the value contained in ERRORCODE to an ASCII value:
  3442.  
  3443.  
  3444.  
  3445.                                              - 54 -
  3446.  
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  
  3452.                       > ERROR:
  3453.                       > SV1 = VALTOSTR(ERRORCODE)
  3454.                       > PROMPT (SV1)
  3455.  
  3456.                       VCLEAR()
  3457.                       Function: Deletes all variables and their associated
  3458.                                 resources except the ERRORCODE variable
  3459.                                 and the Script Variables
  3460.  
  3461.                       Syntax:
  3462.  
  3463.                            > VCLEAR()
  3464.  
  3465.                       Note:  To remove only a single variable and its
  3466.                       resources, use the VDELETE() function.
  3467.  
  3468.                       VDEFINED (arg1)
  3469.                       Function: Tests for the existance of a variable and
  3470.                                 returns a TRUE or FALSE value result
  3471.                       Syntax:
  3472.  
  3473.                            > VDEFINED (variable_name)
  3474.  
  3475.                       where:
  3476.  
  3477.                       VARIABLE_NAME is the name of the variable.
  3478.  
  3479.                       This function is used in an IF command to check if a
  3480.                       variable has been defined.  If the variable exists,
  3481.                       True is returned, else False is returned.  The
  3482.                       result of this function may be inverted by using the
  3483.                       not operator (!).
  3484.  
  3485.                       Examples:
  3486.  
  3487.                       > VAL = 6
  3488.                       > IF VDEFINED(VAL)
  3489.  
  3490.                       would return a True, while:
  3491.  
  3492.                       > IF !VDEFINED(VAR_NAME)
  3493.  
  3494.                       would return False if VAR_NAME had been defined
  3495.                       previously.
  3496.  
  3497.                       VDELETE (arg1)
  3498.                       Function: Deletes the specified variable and any
  3499.                                 associated resources
  3500.                       Syntax:
  3501.  
  3502.                            > VDELETE (variable_name)
  3503.  
  3504.  
  3505.  
  3506.  
  3507.  
  3508.  
  3509.                                              - 55 -
  3510.  
  3511.  
  3512.  
  3513.  
  3514.  
  3515.  
  3516.                       where:
  3517.  
  3518.                       VARIABLE_NAME is the variable to be deleted.
  3519.  
  3520.                       WAIT ()
  3521.                       Function: Wait for an event and return an event code
  3522.                                 numeric value
  3523.                       Syntax:
  3524.  
  3525.                            > WAIT()
  3526.  
  3527.                       The returned event code will be:
  3528.  
  3529.                          0        to indicate a timeout.
  3530.                          -1       to indicate a carrier transition, either
  3531.                                   up to down or down to up.
  3532.                       Any other code will be the ASCII character of a
  3533.                       keystroke.
  3534.  
  3535.                       Examples:
  3536.  
  3537.                       To delay until any event takes place, simply use:
  3538.  
  3539.                       > WAIT()
  3540.  
  3541.                       To test for a particular event, use:
  3542.  
  3543.                       > EVENT = WAIT()
  3544.                       > IF EVENT == 0
  3545.                       > GOTO LABEL_A
  3546.                       > ENDIF
  3547.                       > GOTO LABEL_B
  3548.  
  3549.                       WRITE (arg1,arg2)
  3550.                       Function: Writes a text string to an open file
  3551.                       Syntax:
  3552.  
  3553.                            > WRITE (filedef,text)
  3554.  
  3555.                       where:
  3556.  
  3557.                       FILEDEF must be the name of a variable that contains
  3558.                       the handle returned by a previous file open
  3559.                       function.
  3560.  
  3561.                       TEXT is the text to write.
  3562.  
  3563.                       A newline sequence (CR/LF) is not appended to the
  3564.                       text written to the file.  The position pointer in
  3565.                       the file will move to the next character after the
  3566.                       text is written.
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.                                              - 56 -
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.                       Examples:
  3581.  
  3582.                       > WRITE (FILEDEF,'Testing...')
  3583.                             or
  3584.                       > TXT = 'Total Orders Shipped This Month = '
  3585.                       > RESULT = WRITE (FILDEF,TXT)
  3586.  
  3587.                       On completion of the command, a result code is
  3588.                       returned to the variable RESULT.  A result code of 0
  3589.                       (zero) means the command was successful;  a non-zero
  3590.                       value indicates that the command was not successful.
  3591.  
  3592.                       WRITELINE (arg1,arg2)
  3593.                       Function: Writes a line of text to an open file
  3594.                       Syntax:
  3595.  
  3596.                            > WRITELINE (filedef,text)
  3597.  
  3598.                       where:
  3599.  
  3600.                       FILEDEF must be the name of a variable that contains
  3601.                       the handle returned by a previous file open
  3602.                       function.
  3603.  
  3604.                       TEXT is the text to write.
  3605.  
  3606.                       A newline sequence (CR/LF) will be written to the
  3607.                       file after the text has been written to the file,
  3608.                       and the position pointer in the file will move to
  3609.                       the next character after the newline sequence.
  3610.  
  3611.                       Examples:
  3612.  
  3613.                       > WRITELINE (FILEDEF,'Testing...')
  3614.                             or
  3615.                       > TXT = 'Total Orders Shipped This Month:'
  3616.                       > RESULT = WRITELINE (FILDEF,TXT)
  3617.  
  3618.                       If an error occurs, processing will continue at the
  3619.                       label specified by the ONERR directive, or the
  3620.                       script will terminate.
  3621.  
  3622.                       XMIT_WAIT (arg1,arg2,......,arg12)
  3623.                       Function: Send a text string, wait for 1 of 10
  3624.                                 optional specified replies, and return the
  3625.                                 numeric value of the response received.
  3626.                       Syntax:
  3627.  
  3628.                            > XMIT_WAIT  (text_string,echo_option,
  3629.                                   reply_1,...,reply_10)
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.                                              - 57 -
  3638.  
  3639.  
  3640.  
  3641.  
  3642.  
  3643.  
  3644.                       where:
  3645.  
  3646.                       TEXT_STRING is the string to transmit.  The string
  3647.                       can contain a maximum of 255 characters.
  3648.  
  3649.                       ECHO_OPTION can be ON or OFF (the default).  If set
  3650.                       to ON, the caller's input in response to the
  3651.                       transmitted string will be echoed back.  Otherwise,
  3652.                       the input will not be visible to the caller.
  3653.  
  3654.                       REPLY_1 through REPLY_10 are 10 optional text string
  3655.                       responses.  These strings can contain a maximum of
  3656.                       32 characters.
  3657.  
  3658.                       A value of zero is returned if a timeout occurs
  3659.                       without receiving any of the 10 strings.
  3660.  
  3661.                       Important:  This function often will be used to
  3662.                       provide the 'arg1' value to an ON() function.
  3663.  
  3664.                       Example:
  3665.  
  3666.                       > ARG1_VAL = XMIT_WAIT (xmit_str,,arg2,...,arg12)
  3667.                       > ON (ARG1_VAL,label_1,label_2,...,label_10)
  3668.  
  3669.                       Window Control Functions
  3670.  
  3671.                       WATCH (arg1,arg2,arg3)
  3672.                       Function: Enable or disable the display of script
  3673.                                 file commands and error messages in the
  3674.                                 script window
  3675.                       Syntax:
  3676.  
  3677.                            > WATCH (on_off,errors,errortimeout)
  3678.  
  3679.                       where:
  3680.  
  3681.                       ON_OFF specifies the default setting for displaying
  3682.                       script commands as they are processed.  If set to
  3683.                       ON, the commands will be displayed.  If arg1 of the
  3684.                       WINDOWPRMS() function is set to ON, the script
  3685.                       window will contain a menu which can be used to
  3686.                       override this argument.
  3687.  
  3688.                       ERRORS defines whether or not error and information
  3689.                       messages will be displayed.  If set to ON, error
  3690.                       messages will be displayed, even if the WINDOWSHOW()
  3691.                       function is not used.
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.                                              - 58 -
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.  
  3708.                       ERRORTIMEOUT is a numeric value which sets the
  3709.                       amount of time, in seconds, that an error message
  3710.                       will be displayed before it is cleared.  Valid
  3711.                       values are:
  3712.  
  3713.                       0           Do not clear the error message.
  3714.                       1 - 255     Valid number of seconds
  3715.  
  3716.                       Examples:
  3717.  
  3718.                       > WATCH (ON,ON,0) ; display commands as they
  3719.                                         ;  are processed,
  3720.                                         ; display error messages,
  3721.                                         ;  and leave them displayed
  3722.                                         ;  until cancelled
  3723.                       > WATCH (OFF,ON,100)    ; do not display commands,
  3724.                                         ; do display error messages
  3725.                                         ;  and leave them until
  3726.                                         ;  cancelled by the
  3727.                                         ;  operator or until 100
  3728.                                         ;  seconds have elapsed.
  3729.  
  3730.                       WINDOWPOS (arg1,arg2)
  3731.                       Function: Set the upper left corner of a script file
  3732.                                 window
  3733.                       Syntax:
  3734.  
  3735.                            > WINDOWPOS (horizontal,vertical)
  3736.  
  3737.                       where:
  3738.  
  3739.                       HORIZONTAL is the horizontal displacement, in
  3740.                       pixels, from the left edge of the screen.
  3741.  
  3742.                       VERTICAL is the vertical displacement, in pixels,
  3743.                       from the top edge of the screen.
  3744.  
  3745.                       Note1:  Screen positions are zero-relative to the
  3746.                       top left corner.  That is, the top left corner has
  3747.                       the coordinates (0,0).
  3748.  
  3749.                       Note2:  The screen position function is based on
  3750.                       pixels, rather than text column and row.  The base
  3751.                       screen size depends on the video adapter and monitor
  3752.                       being used.  A rough conversion is 8 pixels of
  3753.                       horizontal movement is approximately equal to one
  3754.                       character column, and 14 pixels of vertical movement
  3755.                       is approximately equal to one character row.
  3756.  
  3757.                       Note3:  If this function is not used, the script
  3758.                       window will use the same start coordinates as its
  3759.                       parent runtime, terminal emulation window.
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.                                              - 59 -
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.                       Example:
  3773.  
  3774.                       > WINDOWPOS (50,32)     ; the start point is
  3775.                                               ; approximately at text
  3776.                                               ; column 10 (50/5) and
  3777.                                               ; row 2 (32/16)
  3778.  
  3779.                       WINDOWPRMS (arg1,arg2,arg3)
  3780.                       Function: Set menu and display options to be used by
  3781.                                 a script window
  3782.                       Syntax:
  3783.  
  3784.                            > WINDOWPRMS (menu,scrname_pos,pathname_pos)
  3785.  
  3786.                       where:
  3787.  
  3788.                       MENU can be ON or OFF.  If set to ON, the script
  3789.                       window will have a menu bar and one menu, similar
  3790.                       to:
  3791.  
  3792.                       If arg1 of the WATCH() function is set to OFF, the
  3793.                       Begin display option will be active and the End
  3794.                       display option will be greyed.  Select Begin display
  3795.                       to show the script commands, as they are processed,
  3796.                       in the client area.  Conversely, if arg1 of the
  3797.                       WATCH() function is set to ON, the End display
  3798.                       option will be active and the Begin display option
  3799.                       will be greyed.
  3800.  
  3801.  
  3802.                       SCRNAME_POS is the numeric priority which determines
  3803.                       if and where the name of the running script file
  3804.                       will be displayed.  Valid numeric values are:
  3805.  
  3806.                       0           Do not display the name of the running
  3807.                                   script file
  3808.                       1 - 127     Display the name above the client area
  3809.                       129 - 255   Display the name below the client area
  3810.  
  3811.                       PATHNAME_POS is the numeric priority which
  3812.                       determines if and where the name of the current
  3813.                       directory will be displayed.  Valid numeric values
  3814.                       are:
  3815.  
  3816.                       0           Do not display the name of the current
  3817.                                   directory
  3818.                       1 - 127     Display the name above the client area
  3819.                       129 - 255   Display the name below the client area
  3820.  
  3821.                       Note:  If both names are to be displayed either
  3822.                       above or below the client area, the name having the
  3823.                       lower value will be displayed first.
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.                                              - 60 -
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.  
  3836.                       Examples:
  3837.  
  3838.                       > WINDOWPRMS (OFF,0,0)  ; neither menu nor names
  3839.                                               ; are displayed
  3840.                       > WINDOWPRMS (ON,1,129) ; the script menu is
  3841.                                               ; displayed, the script
  3842.                                               ; name is displayed
  3843.                                               ; above the client area,
  3844.                                               ; and the current
  3845.                                               ; directory is displayed
  3846.                                               ; below the client area.
  3847.  
  3848.                       WINDOWSHOW ()
  3849.                       Function: Cause the script window to be displayed
  3850.                       Syntax:
  3851.  
  3852.                            > WINDOWSHOW ()
  3853.  
  3854.                       If this function is not used, no script window will
  3855.                       be displayed.  If arg2 of the WATCH() function is
  3856.                       set to ON, however, error and information messages
  3857.                       still will be displayed.
  3858.  
  3859.                       WINDOWSIZE (arg1,arg2)
  3860.                       Function: Set the size of the client area of a
  3861.                                 script file window
  3862.                       Syntax:
  3863.  
  3864.                            > WINDOWPOS (rows,columns)
  3865.  
  3866.                       where:
  3867.  
  3868.                       ROWS is the number of screen rows which will be used
  3869.                       by the script window's client area.
  3870.  
  3871.                       COLUMNS is the number of screen columns which will
  3872.                       be used by the script window's client area.
  3873.  
  3874.                       Note1:  If this function is not used, the script
  3875.                       window will be the size of its parent runtime,
  3876.                       terminal emulation window.
  3877.                       Note2:  If this function is used after the script
  3878.                       window has been displayed using the WINDOWSHOW
  3879.                       function, it only may be used to make the window
  3880.                       smaller.
  3881.  
  3882.                       Example:
  3883.  
  3884.                       > WINDOWSIZE (1,15)
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.  
  3891.  
  3892.  
  3893.                                              - 61 -
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.  
  3900.                       WINDOWTITLE (arg1)
  3901.                       Function: Provide a title for a script file window
  3902.                       Syntax:
  3903.  
  3904.                            > WINDOWTITLE ('title')
  3905.  
  3906.                       where:
  3907.  
  3908.                       TITLE is the text string to place in the script
  3909.                       window's title bar.
  3910.  
  3911.                       Note:  If this function is not used, the title will
  3912.                       default to:
  3913.  
  3914.                       Softerm script - session_name
  3915.  
  3916.                       Examples:
  3917.  
  3918.                       > WINDOWTITLE ('Time')  ; Time is the title
  3919.                       > WINDOWTITLE ('')      ; title bar is blank
  3920.  
  3921.                       CLOCK.SCR
  3922.  
  3923.                       This example shows how the script window control
  3924.                       functions work together to display the current time.
  3925.                       Create CLOCK.SCR using any editor which can save
  3926.                       files in standard ASCII form, and make a Script
  3927.                       profile so you can run this example from a Session
  3928.                       Window.  You might want to play with the different
  3929.                       argument settings to see how they affect the
  3930.                       operation and appearance.
  3931.  
  3932.                       > WINDOWPOS (0,0)       ;start the window in
  3933.                                               ; the upper left corner
  3934.                       > WINDOWTITLE ('Time')  ;the title
  3935.                       > WINDOWSIZE (1,14)     ;the window client area
  3936.                                               ; is 1 row by 14 columns
  3937.                       > WINDOWPRMS (OFF,0,0)  ;no menu and no file or
  3938.                                               ; directory name display
  3939.                       > WATCH (OFF,ON,10)     ;don't show commands as
  3940.                                               ; they're processed,
  3941.                                               ; error messages will be
  3942.                                               ; displayed for 10 sec.
  3943.                       > WINDOWSHOW ()         ;enable the window
  3944.                       > TIMEOUT = 1           ;1-second delay for the
  3945.                                               ; WAIT() function
  3946.                       > LOOP:
  3947.                       > MESSAGE ('   ' + time + '   ')    ;see Note
  3948.                       > IF (WAIT() != 0)      ;if a key is pressed
  3949.                       > END                   ;end operation
  3950.                       > ENDIF
  3951.                       > GOTO LOOP             ;else, continue
  3952.  
  3953.  
  3954.  
  3955.  
  3956.  
  3957.                                              - 62 -
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.                       Note:  The Message consists of the catenation of 3
  3965.                       spaces, the system time (11 characters), and 3 more
  3966.                       spaces.  This centers the time in the 14 columns
  3967.                       specified for the client area.
  3968.  
  3969.                       The Message function writes the text string to the
  3970.                       last line of the client area.  Because the specified
  3971.                       area is only 1 line deep, it appears as though the
  3972.                       time is continually updated.  Actually, the messages
  3973.                       are scrolled up off the display.
  3974.  
  3975.  
  3976.  
  3977.  
  3978.  
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.                                              - 63 -
  4022.